@woosh/meep-engine 3.14.1 → 3.14.3

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

@@ -0,0 +1,32 @@
+/**
+ * Read a KTX2 file into the texel payload the engine uploads.
+ *
+ * The engine's door to {@link ktx2_read}. The reader answers to the file — what format its levels
+ * are in, and that each is the size that format implies — and returns a plain {@link TexelPayload};
+ * this is where that record becomes a {@link ShadeTexelData}, and where the engine's own constraints
+ * on it are applied. Two are worth naming, and both are refusals of well-formed files that the reader
+ * therefore does not make:
+ *
+ * - **A payload is one level or the whole chain.** Two levels of a four-level pyramid is a legal KTX2
+ *   file, but the mip generator cannot start from level 2 and "how many levels does this texture
+ *   have" would have two answers. `ShadeTexelData` refuses it.
+ * - **A payload is one image.** The reader returns array textures and cube maps with their layers
+ *   and faces packed into each level; `ShadeTexelData` reads its third extent as a volume that halves
+ *   per level, so it has nowhere to put a layer. Refused here, by name, until the engine type grows
+ *   one — at which point this is the only place that changes.
+ *
+ * Beside the type it produces rather than beside the format it reads, because it changes when
+ * `ShadeTexelData` does and not when the KTX2 specification does.
+ *
+ * @param {ArrayBuffer|Uint8Array} bytes the whole file
+ * @param {TextureFormat|TextureFormat[]} [transcode_target] what a Basis payload should become — see
+ * {@link ktx2_read}, which owns the rules
+ * @returns {ShadeTexelData}
+ * @throws {Error} everything {@link ktx2_read} throws, a partial mip chain, and an array or cube map
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function texel_data_from_ktx2(bytes: ArrayBuffer | Uint8Array, transcode_target?: TextureFormat | TextureFormat[]): ShadeTexelData;
+import { ShadeTexelData } from "./ShadeTexelData.js";
+//# sourceMappingURL=texel_data_from_ktx2.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"texel_data_from_ktx2.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/source/texel_data_from_ktx2.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,4CATW,WAAW,GAAC,UAAU,qBACtB,gBAAc,eAAe,GAE3B,cAAc,CAqB1B;+BA9C8B,qBAAqB"}

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

@@ -0,0 +1,48 @@
+import { ktx2_read } from "../../../../format/texture/ktx2/ktx2_read.js";
+import { ShadeTexelData } from "./ShadeTexelData.js";
+
+/**
+ * Read a KTX2 file into the texel payload the engine uploads.
+ *
+ * The engine's door to {@link ktx2_read}. The reader answers to the file — what format its levels
+ * are in, and that each is the size that format implies — and returns a plain {@link TexelPayload};
+ * this is where that record becomes a {@link ShadeTexelData}, and where the engine's own constraints
+ * on it are applied. Two are worth naming, and both are refusals of well-formed files that the reader
+ * therefore does not make:
+ *
+ * - **A payload is one level or the whole chain.** Two levels of a four-level pyramid is a legal KTX2
+ *   file, but the mip generator cannot start from level 2 and "how many levels does this texture
+ *   have" would have two answers. `ShadeTexelData` refuses it.
+ * - **A payload is one image.** The reader returns array textures and cube maps with their layers
+ *   and faces packed into each level; `ShadeTexelData` reads its third extent as a volume that halves
+ *   per level, so it has nowhere to put a layer. Refused here, by name, until the engine type grows
+ *   one — at which point this is the only place that changes.
+ *
+ * Beside the type it produces rather than beside the format it reads, because it changes when
+ * `ShadeTexelData` does and not when the KTX2 specification does.
+ *
+ * @param {ArrayBuffer|Uint8Array} bytes the whole file
+ * @param {TextureFormat|TextureFormat[]} [transcode_target] what a Basis payload should become — see
+ * {@link ktx2_read}, which owns the rules
+ * @returns {ShadeTexelData}
+ * @throws {Error} everything {@link ktx2_read} throws, a partial mip chain, and an array or cube map
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function texel_data_from_ktx2(bytes, transcode_target = undefined) {
+    const payload = ktx2_read(bytes, transcode_target);
+
+    if (payload.layers > 1 || payload.faces > 1) {
+        throw new Error(
+            `KTX2: the file is ${payload.faces > 1 ? "a cube map" : `an array of ${payload.layers} layers`},`
+            + ` and ShadeTexelData models a single 2D or 3D image — its depth is a volume that halves`
+            + ` per level, so a layer has nowhere to go. The reader returned them; the engine cannot`
+            + ` take them yet.`
+        );
+    }
+
+    return new ShadeTexelData(
+        payload.format, payload.width, payload.height, payload.depth, payload.levels
+    );
+}

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":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,iFAJW,MAAM,SACN,YAAY,GACV,IAAI,CAiDhB"}

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

@@ -0,0 +1,87 @@
+import { assert } from "../../../core/assert.js";
+import {
+    gpu_texture_format_level_bytes,
+    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 { 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`
+    );
+
+    /*
+     The copy is sized in whole blocks. A block format's 2x2 and 1x1 tail levels are each one block,
+     and the device refuses a copy whose extent is not a multiple of the block — so the extent
+     written is the level's physical size, which for a 1x1-block format is the same thing. Found on
+     hardware: every BC chain's tail had been refused with `copySize.width (2) is not a multiple of
+     compressed texture format block width (4)`, silently, since validation errors do not throw.
+    */
+    const physical = gpu_texture_format_physical_size(format, extent[0], extent[1]);
+
+    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,
+        },
+        [physical[0], physical[1], extent[2]]
+    );
+}

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"}