@woosh/meep-engine 3.14.0 → 3.14.2

package/src/shade/renderer/texture/source/ShadeTexelData.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Texels that are already in a GPU format, with their mip levels.
+ *
+ * The general case of image data, not a special one: an uncompressed image is this with a 1×1 block.
+ * What separates it from the {@link Sampler2D} and `ArrayBuffer` sources beside it is that the format
+ * is *stated* rather than inferred from a channel count and a data type — which is the only way to
+ * describe block-compressed texels, since a BC7 block has no per-texel anything to inspect.
+ *
+ * Rows are tightly packed rows of *blocks*, with no padding between rows or between levels, which is
+ * exactly what {@link gpu_texture_format_row_bytes} and {@link gpu_texture_format_row_count}
+ * describe and what `queue.writeTexture` takes directly.
+ *
+ * `depth` halves per level, matching {@link ShadeTexture.from}, which reads a depth above 1 as a 3D
+ * texture. Array textures are not modelled here because they are not modelled there either.
+ */
+export class ShadeTexelData {
+    /**
+     * Bytes one level of a tightly packed payload occupies.
+     *
+     * @param {GPUTextureFormat} format
+     * @param {number} width base level, texels
+     * @param {number} height base level, texels
+     * @param {number} depth base level
+     * @param {number} level
+     * @returns {number}
+     */
+    static level_byte_length(format: GPUTextureFormat, width: number, height: number, depth: number, level: number): number;
+    /**
+     * @param {GPUTextureFormat} format
+     * @param {number} width
+     * @param {number} height
+     * @param {number} depth
+     * @param {(Uint8Array|undefined)[]} levels
+     */
+    constructor(format: GPUTextureFormat, width: number, height: number, depth: number, levels: (Uint8Array | undefined)[]);
+    /**
+     * @type {GPUTextureFormat}
+     * @readonly
+     */
+    readonly format: GPUTextureFormat;
+    /**
+     * Texels of the base level.
+     * @type {number}
+     * @readonly
+     */
+    readonly width: number;
+    /**
+     * @type {number}
+     * @readonly
+     */
+    readonly height: number;
+    /**
+     * @type {number}
+     * @readonly
+     */
+    readonly depth: number;
+    /**
+     * One entry per mip, index 0 = base.
+     *
+     * An entry may be `undefined` — a level that has not arrived yet. A texture streams in level by
+     * level, so "the chain has 12 levels and 4 of them are here" is an ordinary state, distinct from
+     * a payload that declares a chain it does not have (which is rejected below).
+     *
+     * @type {(Uint8Array|undefined)[]}
+     * @readonly
+     */
+    readonly levels: (Uint8Array | undefined)[];
+    /**
+     * @returns {number} how many levels this payload declares, arrived or not
+     */
+    get level_count(): number;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isShadeTexelData: boolean;
+}
+//# sourceMappingURL=ShadeTexelData.d.ts.map

package/src/shade/renderer/texture/source/ShadeTexelData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShadeTexelData.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/source/ShadeTexelData.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;GAcG;AACH;IAyGI;;;;;;;;;OASG;IACH,0DANW,MAAM,UACN,MAAM,SACN,MAAM,SACN,MAAM,GACJ,MAAM,CAQlB;IAnFD;;;;;;OAMG;IACH,6CALW,MAAM,UACN,MAAM,SACN,MAAM,UACN,CAAC,UAAU,GAAC,SAAS,CAAC,EAAE,EA4DlC;IAtGD;;;OAGG;IACH,kCAAO;IAEP;;;;OAIG;IACH,gBAHU,MAAM,CAGV;IAEN;;;OAGG;IACH,iBAHU,MAAM,CAGT;IAEP;;;OAGG;IACH,gBAHU,MAAM,CAGV;IAEN;;;;;;;;;OASG;IACH,iBAHU,CAAC,UAAU,GAAC,SAAS,CAAC,EAAE,CAG3B;IAuFP;;OAEG;IACH,0BAEC;IAGL;;;OAGG;IACH,2BAFU,OAAO,CAEwB;CANxC"}

package/src/shade/renderer/texture/source/ShadeTexelData.js

@@ -0,0 +1,158 @@
+import { assert } from "../../../../core/assert.js";
+import {
+    gpu_texture_format_info,
+    gpu_texture_format_level_bytes
+} from "../../../descriptor/texture/format/gpu_texture_format_info.js";
+import { texture_mip_extent, texture_mip_level_count } from "../../../util/texture_mip_extent.js";
+
+/**
+ * Texels that are already in a GPU format, with their mip levels.
+ *
+ * The general case of image data, not a special one: an uncompressed image is this with a 1×1 block.
+ * What separates it from the {@link Sampler2D} and `ArrayBuffer` sources beside it is that the format
+ * is *stated* rather than inferred from a channel count and a data type — which is the only way to
+ * describe block-compressed texels, since a BC7 block has no per-texel anything to inspect.
+ *
+ * Rows are tightly packed rows of *blocks*, with no padding between rows or between levels, which is
+ * exactly what {@link gpu_texture_format_row_bytes} and {@link gpu_texture_format_row_count}
+ * describe and what `queue.writeTexture` takes directly.
+ *
+ * `depth` halves per level, matching {@link ShadeTexture.from}, which reads a depth above 1 as a 3D
+ * texture. Array textures are not modelled here because they are not modelled there either.
+ */
+export class ShadeTexelData {
+    /**
+     * @type {GPUTextureFormat}
+     * @readonly
+     */
+    format;
+
+    /**
+     * Texels of the base level.
+     * @type {number}
+     * @readonly
+     */
+    width;
+
+    /**
+     * @type {number}
+     * @readonly
+     */
+    height;
+
+    /**
+     * @type {number}
+     * @readonly
+     */
+    depth;
+
+    /**
+     * One entry per mip, index 0 = base.
+     *
+     * An entry may be `undefined` — a level that has not arrived yet. A texture streams in level by
+     * level, so "the chain has 12 levels and 4 of them are here" is an ordinary state, distinct from
+     * a payload that declares a chain it does not have (which is rejected below).
+     *
+     * @type {(Uint8Array|undefined)[]}
+     * @readonly
+     */
+    levels;
+
+    /**
+     * @param {GPUTextureFormat} format
+     * @param {number} width
+     * @param {number} height
+     * @param {number} depth
+     * @param {(Uint8Array|undefined)[]} levels
+     */
+    constructor(format, width, height, depth, levels) {
+        // throws for a name that is not a GPUTextureFormat, which is the first thing worth knowing
+        // about a payload claiming to be in one
+        gpu_texture_format_info(format);
+
+        assert.isNonNegativeInteger(width, 'width');
+        assert.isNonNegativeInteger(height, 'height');
+        assert.isNonNegativeInteger(depth, 'depth');
+
+        assert.greaterThan(width, 0, 'width');
+        assert.greaterThan(height, 0, 'height');
+        assert.greaterThan(depth, 0, 'depth');
+
+        assert.isArray(levels, 'levels');
+        assert.greaterThan(levels.length, 0, 'levels.length');
+
+        /*
+         One level, or the whole chain. Nothing in between.
+
+         A partial chain would leave the mip generator asked to start from some level other than 0,
+         which it cannot do, and would make "how many levels does this texture have" a question with
+         two answers. A chain whose levels have not all *arrived* is a different thing and is legal —
+         that is a hole in `levels`, not a short `levels`.
+        */
+        // "3d" for the same reason `level_byte_length` uses it: a payload's depth is a volume, and
+        // a volume deeper than it is wide has a chain longer than its width alone implies
+        const full_chain = texture_mip_level_count(width, height, depth, "3d");
+
+        if (levels.length !== 1 && levels.length !== full_chain) {
+            throw new Error(
+                `levels.length must be 1 or ${full_chain} (the full chain for`
+                + ` ${width}x${height}x${depth}), got ${levels.length}`
+            );
+        }
+
+        for (let level = 0; level < levels.length; level++) {
+            const bytes = levels[level];
+
+            if (bytes === undefined) {
+                // not arrived yet
+                continue;
+            }
+
+            const expected = ShadeTexelData.level_byte_length(format, width, height, depth, level);
+
+            if (bytes.byteLength !== expected) {
+                throw new Error(
+                    `level ${level} of a ${width}x${height}x${depth} '${format}' payload should be`
+                    + ` ${expected} bytes, got ${bytes.byteLength}`
+                );
+            }
+        }
+
+        this.format = format;
+        this.width = width;
+        this.height = height;
+        this.depth = depth;
+        this.levels = levels;
+    }
+
+    /**
+     * Bytes one level of a tightly packed payload occupies.
+     *
+     * @param {GPUTextureFormat} format
+     * @param {number} width base level, texels
+     * @param {number} height base level, texels
+     * @param {number} depth base level
+     * @param {number} level
+     * @returns {number}
+     */
+    static level_byte_length(format, width, height, depth, level) {
+        // "3d": a payload's depth is a volume, matching ShadeTexture.from, which reads a depth above
+        // one as a 3D texture
+        const extent = texture_mip_extent(width, height, depth, "3d", level);
+
+        return gpu_texture_format_level_bytes(format, extent[0], extent[1], extent[2]);
+    }
+
+    /**
+     * @returns {number} how many levels this payload declares, arrived or not
+     */
+    get level_count() {
+        return this.levels.length;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+ShadeTexelData.prototype.isShadeTexelData = true;

package/src/shade/renderer/texture/texture_descriptor_from_texture_shade.d.ts

@@ -1,18 +1,8 @@
-/**
- * @param {number} channel_count
- * @param {BinaryDataType} data_type
- * @param {boolean} normalized
- * @param {ColorSpace} color_space
- * @returns {GPUTextureFormat}
- */
-export function infer_format_from_parameters(channel_count: number, data_type: BinaryDataType, normalized: boolean, color_space: ColorSpace): GPUTextureFormat;
 /**
  *
  * @param {ShadeTexture} shade
  * @returns {TextureDescriptor}
  */
 export function texture_descriptor_from_texture_shade(shade: ShadeTexture): TextureDescriptor;
-import { BinaryDataType } from "../../../core/binary/type/BinaryDataType.js";
-import { ColorSpace } from "./ColorSpace.js";
 import { TextureDescriptor } from "../../descriptor/texture/TextureDescriptor.js";
 //# sourceMappingURL=texture_descriptor_from_texture_shade.d.ts.map

package/src/shade/renderer/texture/texture_descriptor_from_texture_shade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"texture_descriptor_from_texture_shade.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/texture_descriptor_from_texture_shade.js"],"names":[],"mappings":"AASA;;;;;;GAMG;AACH,4DANW,MAAM,aACN,cAAc,cACd,OAAO,eACP,UAAU,oBA6EpB;AA2CD;;;;GAIG;AACH,4EAFa,iBAAiB,CAuC7B;+BA/K8B,6CAA6C;2BAIjD,iBAAiB;kCADV,+CAA+C"}
+{"version":3,"file":"texture_descriptor_from_texture_shade.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/texture_descriptor_from_texture_shade.js"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,4EAFa,iBAAiB,CA+D7B;kCAzEiC,+CAA+C"}

package/src/shade/renderer/texture/texture_descriptor_from_texture_shade.js

@@ -1,176 +1,74 @@
-import { BinaryDataType } from "../../../core/binary/type/BinaryDataType.js";
-import { dataTypeByteSize } from "../../../core/binary/type/DataTypeByteSizes.js";
-import { isImageBitmap } from "../../../engine/graphics/texture/isImageBitmap.js";
-import { TextureDescriptor } from "../../descriptor/texture/TextureDescriptor.js";
-import { ColorSpace } from "./ColorSpace.js";
-import { compute_max_mip_count } from "../../util/compute_max_mip_count.js";
-
-import { ShadeTextureFlags } from "./ShadeTextureFlags.js";
-
-/**
- * @param {number} channel_count
- * @param {BinaryDataType} data_type
- * @param {boolean} normalized
- * @param {ColorSpace} color_space
- * @returns {GPUTextureFormat}
- */
-export function infer_format_from_parameters(
-    channel_count,
-    data_type,
-    normalized,
-    color_space
-) {
-
-    // Some channel counts are unsupported, specifically RGB, so we have to go up 1 to RGBA
-    const valid_channel_counts = [1, 2, 4];
-
-    let valid_channel_count = channel_count;
-
-    if (valid_channel_counts.includes(channel_count) === false) {
-        for (let i = 0; i < valid_channel_counts.length; i++) {
-            let vs = valid_channel_counts[i];
-
-            if (channel_count < vs) {
-                valid_channel_count = vs;
-                break;
-            }
-        }
-    }
-
-    const prefix = 'rgba'.slice(0, valid_channel_count);
-
-    const byte_size = dataTypeByteSize(data_type);
-
-    const bit_size = byte_size * 8;
-
-    let ending;
-    if (color_space === ColorSpace.LinearSRGB) {
-        if (data_type === BinaryDataType.Uint8) {
-            ending = "unorm";
-        } else if (data_type === BinaryDataType.Float32) {
-            ending = "float";
-        } else if (data_type === BinaryDataType.Float16 || data_type === BinaryDataType.Uint16) {
-            // Half-float HDR data (e.g. octahedral environment maps). parse_rgbe stores f16 bit
-            // patterns in a Uint16Array, so the same half-float payload can be classified as either
-            // Float16 or Uint16 depending on the runtime — both map to the 16-bit float format.
-            ending = "float";
-        } else {
-            throw new Error(`Unsupported data type '${data_type}'`);
-        }
-    } else if (color_space === ColorSpace.None) {
-        if (
-            data_type === BinaryDataType.Uint8
-            || data_type === BinaryDataType.Uint16
-            || data_type === BinaryDataType.Uint32
-        ) {
-            if (normalized) {
-                ending = "unorm";
-            } else {
-                ending = "uint";
-            }
-
-        } else if (
-            data_type === BinaryDataType.Float32
-            || data_type === BinaryDataType.Float16
-        ) {
-            ending = "float";
-        } else {
-            throw new Error(`Unsupported data type '${data_type}'`);
-        }
-    } else if (color_space === ColorSpace.SRGB) {
-        if (data_type === BinaryDataType.Uint8) {
-            ending = "unorm-srgb";
-        } else {
-            throw new Error(`Unsupported data type '${data_type}'`);
-        }
-    } else {
-        throw new Error(`Unsupported color space '${color_space}'`);
-    }
-
-    return `${prefix}${bit_size}${ending}`;
-}
-
-
-/**
- *
- * @param {ShadeImage} image
- * @returns {GPUTextureFormat}
- */
-function inferFormatFromImage(image) {
-    const source = image.source;
-
-    const color_space = image.color_space;
-    if (source.isSampler2D === true) {
-        // is a sampler
-
-        return infer_format_from_parameters(
-            image.channel_count, image.data_type, image.normalized, image.color_space
-        );
-
-    } else if (isImageBitmap(source)) {
-        if (image.data_type === BinaryDataType.Float16) {
-            return "rgba16float";
-        } else if (color_space === ColorSpace.SRGB) {
-            /*
-            Forces conversion from sRGB to linear in the shader
-            @see https://www.w3.org/TR/webgpu/#texture-formats
-             */
-            return "rgba8unorm-srgb"
-        } else {
-            return "rgba8unorm"
-        }
-    } else if (source instanceof ArrayBuffer) {
-        return infer_format_from_parameters(
-            image.channel_count,
-            image.data_type,
-            image.normalized,
-            image.color_space,
-        );
-    } else {
-        throw new Error(`Unsupported image data`);
-    }
-}
-
-/**
- *
- * @param {ShadeTexture} shade
- * @returns {TextureDescriptor}
- */
-export function texture_descriptor_from_texture_shade(shade) {
-
-    const image = shade.image;
-
-    let usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.COPY_SRC;
-
-    let mipLevelCount = 1;
-
-    if ((shade.flags & ShadeTextureFlags.GenerateMipMaps) !== 0) {
-        // need to bind texture for writing for mipmaps
-        usage |= GPUTextureUsage.RENDER_ATTACHMENT;
-
-        mipLevelCount = compute_max_mip_count(image.width, image.height);
-    }
-
-    /**
-     * @type {GPUTextureFormat}
-     */
-    const format = inferFormatFromImage(image);
-
-    let dimension = "1d";
-
-    if (shade.dimensions === 2) {
-        dimension = "2d";
-    } else if (shade.dimensions === 3) {
-        dimension = "3d";
-    }
-
-    return TextureDescriptor.from({
-        label: shade.label,
-        size: [image.width, image.height, image.depth],
-        format,
-        usage: usage,
-        mipLevelCount,
-        dimension,
-    });
-
+import { TextureDescriptor } from "../../descriptor/texture/TextureDescriptor.js";
+import { gpu_texture_format_can_generate_mipmaps } from "./format/gpu_texture_format_can_generate_mipmaps.js";
+import { texture_format_from_shade_image } from "./format/texture_format_from_shade_image.js";
+import { texture_mip_level_count } from "../../util/texture_mip_extent.js";
+
+import { ShadeTextureFlags } from "./ShadeTextureFlags.js";
+
+/**
+ *
+ * @param {ShadeTexture} shade
+ * @returns {TextureDescriptor}
+ */
+export function texture_descriptor_from_texture_shade(shade) {
+
+    const image = shade.image;
+
+    let usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.COPY_SRC;
+
+    /**
+     * @type {GPUTextureFormat}
+     */
+    const format = texture_format_from_shade_image(image);
+
+    /*
+     Two independent things, which used to be one.
+
+     Where the levels come from is a property of the image: it supplies `level_count` of them, and
+     that is how many the texture gets. Whether to run the mip generator is an instruction the caller
+     gives, and it is honoured or it throws — never quietly reinterpreted from what the image happens
+     to carry. Set the flag on an image that already has a chain and the chain is regenerated, which
+     is a real use: a container whose mips were built with a filter you do not want.
+    */
+    const generate = (shade.flags & ShadeTextureFlags.GenerateMipMaps) !== 0;
+
+    let dimension = "1d";
+
+    if (shade.dimensions === 2) {
+        dimension = "2d";
+    } else if (shade.dimensions === 3) {
+        dimension = "3d";
+    }
+
+    let mipLevelCount;
+
+    if (generate) {
+        if (!gpu_texture_format_can_generate_mipmaps(format)) {
+            throw new Error(
+                `${shade.label || 'texture'}: mipmap generation was requested for '${format}',`
+                + ` which cannot be a render attachment. Mips for this format come from whatever`
+                + ` encoded it — supply them in the payload and clear`
+                + ` ShadeTextureFlags.GenerateMipMaps.`
+            );
+        }
+
+        // the generator renders between levels, so the texture has to be bindable for writing
+        usage |= GPUTextureUsage.RENDER_ATTACHMENT;
+
+        // through the dimension: a volume's chain runs down its depth too, so a 4x4x16 asking for
+        // generated mips wants five levels and not the three its width alone implies
+        mipLevelCount = texture_mip_level_count(image.width, image.height, image.depth, dimension);
+    } else {
+        mipLevelCount = image.level_count;
+    }
+
+    return TextureDescriptor.from({
+        label: shade.label,
+        size: [image.width, image.height, image.depth],
+        format,
+        usage: usage,
+        mipLevelCount,
+        dimension,
+    });
+
 }

package/src/shade/renderer/texture/texture_write_level.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Write one mip level of a texture from tightly packed texels.
+ *
+ * **The level, not the image, is the unit.** meep streams: a texture is not a thing that arrives, it
+ * is a thing that keeps arriving. The descriptor is built from a header before any texels exist, the
+ * texture is allocated once at full size, and levels land as they are delivered — so the primitive
+ * has to be "put these bytes in that level", with whole-image upload written on top rather than the
+ * other way around.
+ *
+ * **Layout comes from the format, not from arithmetic.** `channels × bytes_per_channel × width` is
+ * right only for the 1×1-block formats, and is wrong in a way that is easy to miss: the 1×1 mip of a
+ * BC7 texture is a whole 16-byte block, not a sixteenth of one.
+ * {@link gpu_texture_format_row_bytes} rounds up to whole blocks and this asks it rather than
+ * repeating it.
+ *
+ * Everything but the bytes is read off the texture — format, size, dimension. Passing them
+ * separately would be one more pair of things that can disagree, and the texture is the authority on
+ * all three because it is the thing being written into. The extent at a level, including the rule
+ * that only a 3D texture's depth halves, comes from {@link texture_mip_extent}.
+ *
+ * `queue.writeTexture` has **no** `bytesPerRow` alignment requirement, unlike `copyBufferToTexture`
+ * and its multiple of 256. That is what makes a tightly packed payload uploadable with no staging
+ * buffer and no padding, and it is why this is the path for texels that are already in host memory.
+ *
+ * @param {GPUQueue} queue
+ * @param {GPUTexture} texture
+ * @param {number} level mip level to write, 0 = base
+ * @param {BufferSource} bytes rows of blocks, tightly packed, no padding between rows or layers
+ * @returns {void}
+ */
+export function texture_write_level(queue: GPUQueue, texture: GPUTexture, level: number, bytes: BufferSource): void;
+//# sourceMappingURL=texture_write_level.d.ts.map

package/src/shade/renderer/texture/texture_write_level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture_write_level.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/texture_write_level.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,iFAJW,MAAM,SACN,YAAY,GACV,IAAI,CAwChB"}

package/src/shade/renderer/texture/texture_write_level.js

@@ -0,0 +1,77 @@
+import { assert } from "../../../core/assert.js";
+import {
+    gpu_texture_format_level_bytes,
+    gpu_texture_format_row_bytes,
+    gpu_texture_format_row_count
+} from "../../descriptor/texture/format/gpu_texture_format_info.js";
+import { texture_mip_extent } from "../../util/texture_mip_extent.js";
+
+/**
+ * Write one mip level of a texture from tightly packed texels.
+ *
+ * **The level, not the image, is the unit.** meep streams: a texture is not a thing that arrives, it
+ * is a thing that keeps arriving. The descriptor is built from a header before any texels exist, the
+ * texture is allocated once at full size, and levels land as they are delivered — so the primitive
+ * has to be "put these bytes in that level", with whole-image upload written on top rather than the
+ * other way around.
+ *
+ * **Layout comes from the format, not from arithmetic.** `channels × bytes_per_channel × width` is
+ * right only for the 1×1-block formats, and is wrong in a way that is easy to miss: the 1×1 mip of a
+ * BC7 texture is a whole 16-byte block, not a sixteenth of one.
+ * {@link gpu_texture_format_row_bytes} rounds up to whole blocks and this asks it rather than
+ * repeating it.
+ *
+ * Everything but the bytes is read off the texture — format, size, dimension. Passing them
+ * separately would be one more pair of things that can disagree, and the texture is the authority on
+ * all three because it is the thing being written into. The extent at a level, including the rule
+ * that only a 3D texture's depth halves, comes from {@link texture_mip_extent}.
+ *
+ * `queue.writeTexture` has **no** `bytesPerRow` alignment requirement, unlike `copyBufferToTexture`
+ * and its multiple of 256. That is what makes a tightly packed payload uploadable with no staging
+ * buffer and no padding, and it is why this is the path for texels that are already in host memory.
+ *
+ * @param {GPUQueue} queue
+ * @param {GPUTexture} texture
+ * @param {number} level mip level to write, 0 = base
+ * @param {BufferSource} bytes rows of blocks, tightly packed, no padding between rows or layers
+ * @returns {void}
+ */
+export function texture_write_level(queue, texture, level, bytes) {
+    assert.defined(queue, 'queue');
+    assert.defined(texture, 'texture');
+    assert.defined(bytes, 'bytes');
+
+    assert.isNonNegativeInteger(level, 'level');
+    assert.lessThan(level, texture.mipLevelCount, 'level');
+
+    const format = texture.format;
+
+    const extent = texture_mip_extent(
+        texture.width, texture.height, texture.depthOrArrayLayers, texture.dimension, level
+    );
+
+    const bytes_per_row = gpu_texture_format_row_bytes(format, extent[0]);
+    const rows_per_image = gpu_texture_format_row_count(format, extent[1]);
+
+    assert.equal(
+        bytes.byteLength,
+        gpu_texture_format_level_bytes(format, extent[0], extent[1], extent[2]),
+        `byte length for level ${level} of a ${extent.join('x')} '${format}' texture`
+    );
+
+    queue.writeTexture(
+        {
+            texture,
+            mipLevel: level,
+            origin: { x: 0, y: 0, z: 0 },
+        },
+        bytes,
+        {
+            offset: 0,
+            bytesPerRow: bytes_per_row,
+            // required once the copy is more than one layer deep, and harmless before that
+            rowsPerImage: rows_per_image,
+        },
+        extent
+    );
+}

package/src/shade/renderer/texture/texture_write_to_gpu.d.ts

@@ -1,8 +1,15 @@
 /**
+ * Upload an image's texels into a texture.
+ *
+ * `level_count` says how many of the image's levels to write, from the base up, and is required
+ * rather than defaulted: the one caller that wants fewer than all of them — {@link TextureManager},
+ * about to run the mip generator — is the caller least able to have that decision made for it.
+ * Uploading levels the generator is about to overwrite is bytes across the bus for nothing.
  *
  * @param {ShadeImage} image
  * @param {GPUTexture} texture
  * @param {GPUQueue} queue
+ * @param {number} level_count how many levels to write; `image.level_count` for all of them
  */
-export function texture_write_to_gpu(image: ShadeImage, texture: GPUTexture, queue: GPUQueue): void;
+export function texture_write_to_gpu(image: ShadeImage, texture: GPUTexture, queue: GPUQueue, level_count: number): void;
 //# sourceMappingURL=texture_write_to_gpu.d.ts.map

package/src/shade/renderer/texture/texture_write_to_gpu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"texture_write_to_gpu.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/texture_write_to_gpu.js"],"names":[],"mappings":"AAsLA;;;;;GAKG;AACH,oGAoEC"}
+{"version":3,"file":"texture_write_to_gpu.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/texture_write_to_gpu.js"],"names":[],"mappings":"AAyKA;;;;;;;;;;;;GAYG;AACH,2GAFW,MAAM,QAqGhB"}