@woosh/meep-engine 3.14.2 → 3.14.4

package/src/shade/renderer/texture/encode/texture_encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture_encode.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/encode/texture_encode.js"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH;IAf+B,MAAM;IAEA,MAAM;IAEhB,WAAW,EAA3B,MAAM;IACwB,KAAK;IAElB,KAAK,GAAtB,MAAM;IACJ,mBAAmB,CAgH/B"}

package/src/shade/renderer/texture/encode/texture_encode.js

@@ -0,0 +1,168 @@
+import { assert } from "../../../../core/assert.js";
+import { gpu_texture_format_srg_to_linear } from "../format/gpu_texture_format_srg_to_linear.js";
+import { texture_encode_layout, texture_encode_level_table } from "./texture_encode_layout.js";
+import { texture_encode_shader } from "./texture_encode_shader.js";
+
+/**
+ * What {@link texture_encode} produced.
+ *
+ * @typedef {Object} TextureEncodeResult
+ * @property {GPUTexture} texture the block-compressed texture, every requested level written once
+ * the context is submitted. The caller's, to keep and to destroy
+ * @property {GPUBuffer} blocks the block buffer the encoder wrote and the copies read, laid out as
+ * `layout` says. **Transient**: released back to the context's pool when the context finishes, so
+ * anything wanting the raw blocks — a container writer, a cross-check — copies them out before then
+ * @property {TextureEncodeLayout} layout where each level's blocks sit in `blocks`
+ */
+
+/**
+ * Encode a sampleable texture into a block-compressed one, on the device.
+ *
+ * **A texture in, a texture out, and nothing about who wants it.** The caller names the target
+ * format outright — `bc4-r-unorm`, `bc7-rgba-unorm-srgb` — and gets a texture in that format with
+ * `level_count` levels, each encoded from the same level of the source. No role, no preference list,
+ * no material: a subsystem that can encode anything to a named format is what the texture manager, a
+ * container writer, a procedural generator and a test can all stand on, and none of those want it to
+ * have opinions about content.
+ *
+ * WebGPU has no writable block-compressed storage texture, so the shape is the plan's §4.4: one
+ * compute dispatch writes every level's blocks into one storage buffer, and one `copyBufferToTexture`
+ * per level moves them into the texture. The buffer is laid out by {@link texture_encode_layout}
+ * with its rows padded to the copy's 256-byte stride before anything runs — the encoder writes to
+ * the stride the copy will read, and each copy is a whole level, sized in whole blocks as the copy
+ * commands count them.
+ *
+ * **The source is read as stored, not as decoded.** An `-srgb` source would arrive through
+ * `textureLoad` already converted to linear, and an encoder fitting those values into bytes that the
+ * sampler will then decode as sRGB again would encode the wrong picture. So an sRGB source is bound
+ * through a view in its linear twin format, which needs the texture to have been created with that
+ * format in its `viewFormats`; the device refuses the view otherwise, by validation error. The
+ * `-srgb`-ness of the *target* is likewise nothing but the tag the texture is created with: the
+ * encoded bytes are identical for both spellings.
+ *
+ * Everything is recorded into `cmd` and nothing runs until it is submitted. The transient buffers
+ * are the context's and go back to its pool when it finishes.
+ *
+ * @param {ShadeGPUCommandContext} cmd
+ * @param {Object} options
+ * @param {GPUTexture} options.source a 2D, single-layer texture with `TEXTURE_BINDING`, holding at
+ * least `level_count` levels
+ * @param {GPUTextureFormat} options.format the target block format, exactly as the texture is to be
+ * created
+ * @param {number} options.level_count how many levels to encode, from level 0 down
+ * @param {GPUTextureUsageFlags} options.usage the target texture's usage; must include `COPY_DST`,
+ * which is how the blocks get in
+ * @param {string} [options.label] for the target texture
+ * @returns {TextureEncodeResult}
+ * @throws {Error} naming the format, for a target this cannot write; naming the source, for one the
+ * encoder cannot read
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function texture_encode(cmd, { source, format, level_count, usage, label = `encoded ${format}` }) {
+    assert.defined(cmd, 'cmd');
+    assert.defined(source, 'source');
+    assert.isString(format, 'format');
+    assert.isPositiveInteger(level_count, 'level_count');
+    assert.isNonNegativeInteger(usage, 'usage');
+    assert.isString(label, 'label');
+
+    const shader = texture_encode_shader(format);
+
+    if (source.dimension !== "2d" || source.depthOrArrayLayers !== 1) {
+        throw new Error(
+            `texture_encode: source '${source.label}' is ${source.dimension} with ${source.depthOrArrayLayers} layers;`
+            + ` only a single-layer 2D texture can be encoded`
+        );
+    }
+
+    if ((source.usage & GPUTextureUsage.TEXTURE_BINDING) === 0) {
+        throw new Error(`texture_encode: source '${source.label}' was not created with TEXTURE_BINDING, so it cannot be read`);
+    }
+
+    if (level_count > source.mipLevelCount) {
+        throw new Error(
+            `texture_encode: source '${source.label}' holds ${source.mipLevelCount} levels, and ${level_count} were asked for`
+        );
+    }
+
+    if ((usage & GPUTextureUsage.COPY_DST) === 0) {
+        throw new Error(`texture_encode: the target's usage must include COPY_DST, which is how the blocks reach it`);
+    }
+
+    const device = cmd.device;
+
+    const layout = texture_encode_layout(format, source.width, source.height, level_count);
+
+    const binding_limit = device.limits.maxStorageBufferBindingSize;
+
+    if (layout.byte_length > binding_limit) {
+        throw new Error(
+            `texture_encode: the ${layout.levels.length}-level block buffer of a ${source.width}x${source.height} '${format}'`
+            + ` texture is ${layout.byte_length} bytes, over this device's maxStorageBufferBindingSize of ${binding_limit}`
+        );
+    }
+
+    const texture = device.createTexture({
+        label,
+        size: [source.width, source.height, 1],
+        format,
+        mipLevelCount: level_count,
+        usage,
+    });
+
+    const table = texture_encode_level_table(layout);
+
+    const levels = cmd.allocateTransientBufferAndLoad(table.buffer, GPUBufferUsage.STORAGE);
+
+    const blocks = cmd.allocateTransientBuffer(
+        GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+        layout.byte_length
+    );
+
+    const view = source.createView({
+        label: `${source.label} for encoding`,
+        format: source.format.endsWith("-srgb") ? gpu_texture_format_srg_to_linear(source.format) : source.format,
+        dimension: "2d",
+    });
+
+    const group_count = Math.ceil(layout.block_count / shader.group_size_x);
+
+    // one dimension is capped, so a large chain wraps onto a second grid row; the shader reads the
+    // row length from num_workgroups
+    const groups_per_row = Math.min(group_count, device.limits.maxComputeWorkgroupsPerDimension);
+
+    shader.dispatch({
+        encoder: cmd,
+        bindings: {
+            encode_source: view,
+            encode_levels: levels,
+            encode_output: blocks,
+        },
+        group_count_x: groups_per_row,
+        group_count_y: Math.ceil(group_count / groups_per_row),
+    });
+
+    const encoder = cmd.gpu_encoder;
+
+    for (const level of layout.levels) {
+        encoder.copyBufferToTexture(
+            {
+                buffer: blocks,
+                offset: level.byte_offset,
+                bytesPerRow: level.bytes_per_row,
+                rowsPerImage: level.blocks_y,
+            },
+            {
+                texture,
+                mipLevel: level.level,
+                origin: [0, 0, 0],
+            },
+            // sized in whole blocks, as the copy commands count: the 1x1 tail is one 4x4 block
+            [level.copy_width, level.copy_height, 1]
+        );
+    }
+
+    return { texture, blocks, layout };
+}

package/src/shade/renderer/texture/encode/texture_encode_layout.d.ts

@@ -0,0 +1,196 @@
+/**
+ * One mip level's place in the block buffer an encoder writes.
+ *
+ * @typedef {Object} TextureEncodeLevel
+ * @property {number} level the mip level, of the source and of the target alike
+ * @property {number} width texels at this level
+ * @property {number} height texels at this level
+ * @property {number} copy_width the extent the copy is sized in: `width` rounded up to whole blocks
+ * @property {number} copy_height likewise
+ * @property {number} blocks_x blocks per row, partial blocks counted
+ * @property {number} blocks_y rows of blocks
+ * @property {number} first_block where this level's blocks start in the flat sequence every level's
+ * blocks form — the dispatch is one invocation per block over that sequence
+ * @property {number} byte_offset where this level's first row starts in the buffer
+ * @property {number} bytes_per_row stride between rows, padded to {@link COPY_BYTES_PER_ROW_ALIGNMENT}
+ */
+/**
+ * How every level of an encoded texture lies in one block buffer.
+ *
+ * @typedef {Object} TextureEncodeLayout
+ * @property {GPUTextureFormat} format the block format the buffer holds
+ * @property {number} width texels at level 0
+ * @property {number} height texels at level 0
+ * @property {number} bytes_per_block
+ * @property {TextureEncodeLevel[]} levels in mip order
+ * @property {number} block_count over every level
+ * @property {number} byte_length of the whole buffer
+ */
+/**
+ * Lay out the block buffer a compute encoder writes and `copyBufferToTexture` reads, one level after
+ * another, **with every row padded to what the copy demands.**
+ *
+ * `copyBufferToTexture` requires `bytesPerRow` to be a multiple of 256, which `writeTexture` does
+ * not. For a 16-byte-block format a row of blocks is `ceil(w / 4) * 16` bytes, so a mip chain's rows
+ * are naturally aligned only from 64 texels wide upwards, and every level below that needs its rows
+ * padded — a 1x1 mip is a 16-byte block sitting at the head of a 256-byte row. The padding is decided
+ * here, before anything runs, so the encoder writes to a stride it was told and the copy reads the
+ * stride it requires, and neither discovers the rule at the other's expense. Each level's bytes are a
+ * whole number of padded rows, so every level's offset is 256-aligned as well, which covers the
+ * copy's other requirement that the offset be a multiple of the block size.
+ *
+ * Row and block counts come from the format table — a partial block costs a whole block, and that
+ * arithmetic already has a home. So does the size a copy is addressed by: the copy commands count
+ * whole blocks and bound them by the level's *physical* size, so the 2x2 and 1x1 tail of a chain
+ * are copied as 4x4, which is what {@link gpu_texture_format_physical_size} says and what each
+ * level's `copy_width` and `copy_height` carry.
+ *
+ * **The base size must be a whole number of blocks**, because WebGPU refuses to create a compressed
+ * texture whose level 0 is not — only the mip tail may be partial. A source that is not is refused
+ * here by name rather than padded: a target of a different size than its source would shift every
+ * texel coordinate, and that is the caller's decision to make, not this function's to hide.
+ *
+ * @param {GPUTextureFormat} format the target block format
+ * @param {number} width texels at level 0
+ * @param {number} height texels at level 0
+ * @param {number} level_count how many levels the buffer holds, from level 0 down
+ * @returns {TextureEncodeLayout}
+ * @throws {Error} for a level count the texture cannot have, or a base size that is not whole blocks
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function texture_encode_layout(format: GPUTextureFormat, width: number, height: number, level_count: number): TextureEncodeLayout;
+/**
+ * The level table an encoding dispatch reads: the layout above, as the words a shader indexes.
+ *
+ * A flat run of `u32` rather than a struct, deliberately. The same table is bound on the device and
+ * handed to the WGSL emulator in tests, and a flat array is the one representation both take as it
+ * is — a struct would be bytes on one side and objects on the other, and a spec that had to build
+ * each would be a spec of the conversion rather than of the shader. Offsets are in words because the
+ * output is bound as an array of words, and every offset the layout produces is a multiple of four.
+ *
+ * @param {TextureEncodeLayout} layout
+ * @returns {Uint32Array}
+ */
+export function texture_encode_level_table(layout: TextureEncodeLayout): Uint32Array;
+/**
+ * The tightly packed rows of one level, lifted out of a padded block buffer.
+ *
+ * What `copyBufferToTexture` does with the level, done on the host — for a test that decodes what an
+ * encoder wrote, or a tool that wants the level as `texture_write_level` takes it.
+ *
+ * @param {TextureEncodeLayout} layout
+ * @param {Uint8Array} buffer the whole block buffer, `layout.byte_length` long
+ * @param {number} level
+ * @returns {Uint8Array} `blocks_x * blocks_y * bytes_per_block` bytes
+ */
+export function texture_encode_level_blocks(layout: TextureEncodeLayout, buffer: Uint8Array, level: number): Uint8Array;
+/**
+ * Words at the head of the level table: how many levels, then how many blocks in all.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const TEXTURE_ENCODE_LEVEL_TABLE_HEADER_WORDS: number;
+/**
+ * Words per level record. Eight, so a record is a tidy power of two; six carry data.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const TEXTURE_ENCODE_LEVEL_TABLE_RECORD_WORDS: number;
+/**
+ * Where each field sits in a level record, and in the header. The WGSL reader is generated from
+ * these same numbers, which is what keeps the two sides of the table from drifting.
+ */
+export type TextureEncodeLevelWord = number;
+export namespace TextureEncodeLevelWord {
+    let LEVEL_COUNT: number;
+    let BLOCK_COUNT: number;
+    let MIP: number;
+    let WIDTH: number;
+    let HEIGHT: number;
+    let BLOCKS_X: number;
+    let BLOCKS_Y: number;
+    let FIRST_BLOCK: number;
+    let WORD_OFFSET: number;
+    let ROW_STRIDE_WORDS: number;
+}
+/**
+ * One mip level's place in the block buffer an encoder writes.
+ */
+export type TextureEncodeLevel = {
+    /**
+     * the mip level, of the source and of the target alike
+     */
+    level: number;
+    /**
+     * texels at this level
+     */
+    width: number;
+    /**
+     * texels at this level
+     */
+    height: number;
+    /**
+     * the extent the copy is sized in: `width` rounded up to whole blocks
+     */
+    copy_width: number;
+    /**
+     * likewise
+     */
+    copy_height: number;
+    /**
+     * blocks per row, partial blocks counted
+     */
+    blocks_x: number;
+    /**
+     * rows of blocks
+     */
+    blocks_y: number;
+    /**
+     * where this level's blocks start in the flat sequence every level's
+     * blocks form — the dispatch is one invocation per block over that sequence
+     */
+    first_block: number;
+    /**
+     * where this level's first row starts in the buffer
+     */
+    byte_offset: number;
+    /**
+     * stride between rows, padded to {@link COPY_BYTES_PER_ROW_ALIGNMENT }
+     */
+    bytes_per_row: number;
+};
+/**
+ * How every level of an encoded texture lies in one block buffer.
+ */
+export type TextureEncodeLayout = {
+    /**
+     * the block format the buffer holds
+     */
+    format: GPUTextureFormat;
+    /**
+     * texels at level 0
+     */
+    width: number;
+    /**
+     * texels at level 0
+     */
+    height: number;
+    bytes_per_block: number;
+    /**
+     * in mip order
+     */
+    levels: TextureEncodeLevel[];
+    /**
+     * over every level
+     */
+    block_count: number;
+    /**
+     * of the whole buffer
+     */
+    byte_length: number;
+};
+//# sourceMappingURL=texture_encode_layout.d.ts.map

package/src/shade/renderer/texture/encode/texture_encode_layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture_encode_layout.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/encode/texture_encode_layout.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,uEATW,MAAM,UACN,MAAM,eACN,MAAM,GACJ,mBAAmB,CA0E/B;AAuCD;;;;;;;;;;;GAWG;AACH,mDAHW,mBAAmB,GACjB,WAAW,CA0BvB;AAED;;;;;;;;;;GAUG;AACH,oDALW,mBAAmB,UACnB,UAAU,SACV,MAAM,GACJ,UAAU,CAkBtB;AAtGD;;;;;GAKG;AACH,sDAFU,MAAM,CAEyC;AAEzD;;;;;GAKG;AACH,sDAFU,MAAM,CAEyC;;;;;qCAO/C,MAAM;;;;;;;;;;;;;;;;;;;;WAvJF,MAAM;;;;WACN,MAAM;;;;YACN,MAAM;;;;gBACN,MAAM;;;;iBACN,MAAM;;;;cACN,MAAM;;;;cACN,MAAM;;;;;iBACN,MAAM;;;;iBAEN,MAAM;;;;mBACN,MAAM;;;;;;;;;;;;;WAQN,MAAM;;;;YACN,MAAM;qBACN,MAAM;;;;YACN,kBAAkB,EAAE;;;;iBACpB,MAAM;;;;iBACN,MAAM"}

package/src/shade/renderer/texture/encode/texture_encode_layout.js

@@ -0,0 +1,248 @@
+import { assert } from "../../../../core/assert.js";
+import { round_up } from "../../../../core/math/round_up.js";
+import {
+    gpu_texture_format_info,
+    gpu_texture_format_physical_size,
+    gpu_texture_format_row_bytes,
+    gpu_texture_format_row_count
+} from "../../../descriptor/texture/format/gpu_texture_format_info.js";
+import { COPY_BYTES_PER_ROW_ALIGNMENT } from "../../../device/COPY_BYTES_PER_ROW_ALIGNMENT.js";
+import { texture_mip_extent, texture_mip_level_count } from "../../../util/texture_mip_extent.js";
+
+/**
+ * One mip level's place in the block buffer an encoder writes.
+ *
+ * @typedef {Object} TextureEncodeLevel
+ * @property {number} level the mip level, of the source and of the target alike
+ * @property {number} width texels at this level
+ * @property {number} height texels at this level
+ * @property {number} copy_width the extent the copy is sized in: `width` rounded up to whole blocks
+ * @property {number} copy_height likewise
+ * @property {number} blocks_x blocks per row, partial blocks counted
+ * @property {number} blocks_y rows of blocks
+ * @property {number} first_block where this level's blocks start in the flat sequence every level's
+ * blocks form — the dispatch is one invocation per block over that sequence
+ * @property {number} byte_offset where this level's first row starts in the buffer
+ * @property {number} bytes_per_row stride between rows, padded to {@link COPY_BYTES_PER_ROW_ALIGNMENT}
+ */
+
+/**
+ * How every level of an encoded texture lies in one block buffer.
+ *
+ * @typedef {Object} TextureEncodeLayout
+ * @property {GPUTextureFormat} format the block format the buffer holds
+ * @property {number} width texels at level 0
+ * @property {number} height texels at level 0
+ * @property {number} bytes_per_block
+ * @property {TextureEncodeLevel[]} levels in mip order
+ * @property {number} block_count over every level
+ * @property {number} byte_length of the whole buffer
+ */
+
+/**
+ * Lay out the block buffer a compute encoder writes and `copyBufferToTexture` reads, one level after
+ * another, **with every row padded to what the copy demands.**
+ *
+ * `copyBufferToTexture` requires `bytesPerRow` to be a multiple of 256, which `writeTexture` does
+ * not. For a 16-byte-block format a row of blocks is `ceil(w / 4) * 16` bytes, so a mip chain's rows
+ * are naturally aligned only from 64 texels wide upwards, and every level below that needs its rows
+ * padded — a 1x1 mip is a 16-byte block sitting at the head of a 256-byte row. The padding is decided
+ * here, before anything runs, so the encoder writes to a stride it was told and the copy reads the
+ * stride it requires, and neither discovers the rule at the other's expense. Each level's bytes are a
+ * whole number of padded rows, so every level's offset is 256-aligned as well, which covers the
+ * copy's other requirement that the offset be a multiple of the block size.
+ *
+ * Row and block counts come from the format table — a partial block costs a whole block, and that
+ * arithmetic already has a home. So does the size a copy is addressed by: the copy commands count
+ * whole blocks and bound them by the level's *physical* size, so the 2x2 and 1x1 tail of a chain
+ * are copied as 4x4, which is what {@link gpu_texture_format_physical_size} says and what each
+ * level's `copy_width` and `copy_height` carry.
+ *
+ * **The base size must be a whole number of blocks**, because WebGPU refuses to create a compressed
+ * texture whose level 0 is not — only the mip tail may be partial. A source that is not is refused
+ * here by name rather than padded: a target of a different size than its source would shift every
+ * texel coordinate, and that is the caller's decision to make, not this function's to hide.
+ *
+ * @param {GPUTextureFormat} format the target block format
+ * @param {number} width texels at level 0
+ * @param {number} height texels at level 0
+ * @param {number} level_count how many levels the buffer holds, from level 0 down
+ * @returns {TextureEncodeLayout}
+ * @throws {Error} for a level count the texture cannot have, or a base size that is not whole blocks
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function texture_encode_layout(format, width, height, level_count) {
+    assert.isPositiveInteger(width, 'width');
+    assert.isPositiveInteger(height, 'height');
+    assert.isPositiveInteger(level_count, 'level_count');
+
+    const info = gpu_texture_format_info(format);
+
+    if (width % info.block_width !== 0 || height % info.block_height !== 0) {
+        throw new Error(
+            `texture_encode_layout: a ${width}x${height} '${format}' texture cannot exist — WebGPU requires the base`
+            + ` size of a compressed texture to be a multiple of its ${info.block_width}x${info.block_height} block`
+        );
+    }
+
+    const available = texture_mip_level_count(width, height, 1, "2d");
+
+    if (level_count > available) {
+        throw new Error(
+            `texture_encode_layout: a ${width}x${height} texture has ${available} mip levels, not ${level_count}`
+        );
+    }
+
+    /**
+     * @type {TextureEncodeLevel[]}
+     */
+    const levels = [];
+
+    let first_block = 0;
+    let byte_offset = 0;
+
+    for (let level = 0; level < level_count; level++) {
+        const extent = texture_mip_extent(width, height, 1, "2d", level);
+
+        const row_bytes = gpu_texture_format_row_bytes(format, extent[0]);
+
+        const blocks_x = row_bytes / info.bytes_per_block;
+        const blocks_y = gpu_texture_format_row_count(format, extent[1]);
+
+        const bytes_per_row = round_up(row_bytes, COPY_BYTES_PER_ROW_ALIGNMENT);
+
+        const physical = gpu_texture_format_physical_size(format, extent[0], extent[1]);
+
+        levels.push({
+            level,
+            width: extent[0],
+            height: extent[1],
+            copy_width: physical[0],
+            copy_height: physical[1],
+            blocks_x,
+            blocks_y,
+            first_block,
+            byte_offset,
+            bytes_per_row,
+        });
+
+        first_block += blocks_x * blocks_y;
+        byte_offset += bytes_per_row * blocks_y;
+    }
+
+    return {
+        format,
+        width,
+        height,
+        bytes_per_block: info.bytes_per_block,
+        levels,
+        block_count: first_block,
+        byte_length: byte_offset,
+    };
+}
+
+/**
+ * Words at the head of the level table: how many levels, then how many blocks in all.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const TEXTURE_ENCODE_LEVEL_TABLE_HEADER_WORDS = 2;
+
+/**
+ * Words per level record. Eight, so a record is a tidy power of two; six carry data.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const TEXTURE_ENCODE_LEVEL_TABLE_RECORD_WORDS = 8;
+
+/**
+ * Where each field sits in a level record, and in the header. The WGSL reader is generated from
+ * these same numbers, which is what keeps the two sides of the table from drifting.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const TextureEncodeLevelWord = {
+    LEVEL_COUNT: 0,
+    BLOCK_COUNT: 1,
+
+    MIP: 0,
+    WIDTH: 1,
+    HEIGHT: 2,
+    BLOCKS_X: 3,
+    BLOCKS_Y: 4,
+    FIRST_BLOCK: 5,
+    WORD_OFFSET: 6,
+    ROW_STRIDE_WORDS: 7,
+};
+
+/**
+ * The level table an encoding dispatch reads: the layout above, as the words a shader indexes.
+ *
+ * A flat run of `u32` rather than a struct, deliberately. The same table is bound on the device and
+ * handed to the WGSL emulator in tests, and a flat array is the one representation both take as it
+ * is — a struct would be bytes on one side and objects on the other, and a spec that had to build
+ * each would be a spec of the conversion rather than of the shader. Offsets are in words because the
+ * output is bound as an array of words, and every offset the layout produces is a multiple of four.
+ *
+ * @param {TextureEncodeLayout} layout
+ * @returns {Uint32Array}
+ */
+export function texture_encode_level_table(layout) {
+    const record = TEXTURE_ENCODE_LEVEL_TABLE_RECORD_WORDS;
+
+    const words = new Uint32Array(TEXTURE_ENCODE_LEVEL_TABLE_HEADER_WORDS + layout.levels.length * record);
+
+    words[TextureEncodeLevelWord.LEVEL_COUNT] = layout.levels.length;
+    words[TextureEncodeLevelWord.BLOCK_COUNT] = layout.block_count;
+
+    for (let i = 0; i < layout.levels.length; i++) {
+        const level = layout.levels[i];
+
+        const base = TEXTURE_ENCODE_LEVEL_TABLE_HEADER_WORDS + i * record;
+
+        words[base + TextureEncodeLevelWord.MIP] = level.level;
+        words[base + TextureEncodeLevelWord.WIDTH] = level.width;
+        words[base + TextureEncodeLevelWord.HEIGHT] = level.height;
+        words[base + TextureEncodeLevelWord.BLOCKS_X] = level.blocks_x;
+        words[base + TextureEncodeLevelWord.BLOCKS_Y] = level.blocks_y;
+        words[base + TextureEncodeLevelWord.FIRST_BLOCK] = level.first_block;
+        words[base + TextureEncodeLevelWord.WORD_OFFSET] = level.byte_offset / 4;
+        words[base + TextureEncodeLevelWord.ROW_STRIDE_WORDS] = level.bytes_per_row / 4;
+    }
+
+    return words;
+}
+
+/**
+ * The tightly packed rows of one level, lifted out of a padded block buffer.
+ *
+ * What `copyBufferToTexture` does with the level, done on the host — for a test that decodes what an
+ * encoder wrote, or a tool that wants the level as `texture_write_level` takes it.
+ *
+ * @param {TextureEncodeLayout} layout
+ * @param {Uint8Array} buffer the whole block buffer, `layout.byte_length` long
+ * @param {number} level
+ * @returns {Uint8Array} `blocks_x * blocks_y * bytes_per_block` bytes
+ */
+export function texture_encode_level_blocks(layout, buffer, level) {
+    const entry = layout.levels[level];
+
+    assert.defined(entry, `level ${level} of a ${layout.levels.length}-level layout`);
+
+    const row_bytes = entry.blocks_x * layout.bytes_per_block;
+
+    const out = new Uint8Array(row_bytes * entry.blocks_y);
+
+    for (let row = 0; row < entry.blocks_y; row++) {
+        const from = entry.byte_offset + row * entry.bytes_per_row;
+
+        out.set(buffer.subarray(from, from + row_bytes), row * row_bytes);
+    }
+
+    return out;
+}

package/src/shade/renderer/texture/encode/texture_encode_resources.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The three bindings every block encoder has, and nothing else.
+ *
+ * `encode_source` is the texture being encoded, bound as unfilterable float so that every float
+ * format binds — it is only ever read with `textureLoad`, level by level. `encode_levels` is the
+ * table {@link texture_encode_level_table} writes. `encode_output` is the block buffer, as words.
+ *
+ * A fresh descriptor per call, because each shader owns its own; the names are shared because the
+ * chunks that read the source and the table refer to them.
+ *
+ * @returns {ShaderResourceSetDescriptor}
+ */
+export function texture_encode_resources(): ShaderResourceSetDescriptor;
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+//# sourceMappingURL=texture_encode_resources.d.ts.map

package/src/shade/renderer/texture/encode/texture_encode_resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture_encode_resources.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/encode/texture_encode_resources.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,4CAFa,2BAA2B,CAWvC;4CAxB2C,sDAAsD"}

package/src/shade/renderer/texture/encode/texture_encode_resources.js

@@ -0,0 +1,25 @@
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+
+/**
+ * The three bindings every block encoder has, and nothing else.
+ *
+ * `encode_source` is the texture being encoded, bound as unfilterable float so that every float
+ * format binds — it is only ever read with `textureLoad`, level by level. `encode_levels` is the
+ * table {@link texture_encode_level_table} writes. `encode_output` is the block buffer, as words.
+ *
+ * A fresh descriptor per call, because each shader owns its own; the names are shared because the
+ * chunks that read the source and the table refer to them.
+ *
+ * @returns {ShaderResourceSetDescriptor}
+ */
+export function texture_encode_resources() {
+    const resources = new ShaderResourceSetDescriptor();
+
+    resources.createGroup()
+        .addTexture('encode_source', 'unfilterable-float', '2d')
+        .addStorageBuffer('encode_levels', WebGPUArray.u32, false)
+        .addStorageBuffer('encode_output', WebGPUArray.u32, true);
+
+    return resources;
+}