@woosh/meep-engine 3.14.1 → 3.14.3

package/src/shade/renderer/texture/format/texture_variant_select.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Which encoding of a texture to fetch.
+ *
+ * The end of the chain {@link gpu_texture_compression_support} and {@link texture_format_preference}
+ * begin: what this device can sample, then what the engine would prefer for this kind of content,
+ * then — here — the best of those that somebody actually built.
+ *
+ * **Returns a path and nothing else.** Not the format it chose, because the caller does not need it:
+ * a reader determines a payload's format from the payload's own header, which is the only source
+ * that cannot be wrong. Handing back a format alongside would invite someone to trust the manifest
+ * over the bytes.
+ *
+ * **Always answers.** A device that supports no compression, or one whose preferred formats were
+ * never built, gets {@link TextureVariantSet.fallback} — the same path a tool or a test would ask
+ * for. There is no "nothing suitable" case for a caller to handle, because a texture with no
+ * universally readable encoding is a broken manifest rather than a runtime condition.
+ *
+ * @param {TextureVariantSet} variants what was built for this texture
+ * @param {TextureRole|number} role what the texture is for
+ * @param {Set<GPUTextureFormat>} support what this device can sample
+ * @returns {string} the path to fetch
+ */
+export function texture_variant_select(variants: TextureVariantSet, role: TextureRole | number, support: Set<GPUTextureFormat>): string;
+//# sourceMappingURL=texture_variant_select.d.ts.map

package/src/shade/renderer/texture/format/texture_variant_select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture_variant_select.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/format/texture_variant_select.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,0EAJW,cAAY,MAAM,WAClB,qBAAqB,GACnB,MAAM,CAclB"}

package/src/shade/renderer/texture/format/texture_variant_select.js

@@ -0,0 +1,38 @@
+import { assert } from "../../../../core/assert.js";
+import { texture_format_preference } from "./texture_format_preference.js";
+
+/**
+ * Which encoding of a texture to fetch.
+ *
+ * The end of the chain {@link gpu_texture_compression_support} and {@link texture_format_preference}
+ * begin: what this device can sample, then what the engine would prefer for this kind of content,
+ * then — here — the best of those that somebody actually built.
+ *
+ * **Returns a path and nothing else.** Not the format it chose, because the caller does not need it:
+ * a reader determines a payload's format from the payload's own header, which is the only source
+ * that cannot be wrong. Handing back a format alongside would invite someone to trust the manifest
+ * over the bytes.
+ *
+ * **Always answers.** A device that supports no compression, or one whose preferred formats were
+ * never built, gets {@link TextureVariantSet.fallback} — the same path a tool or a test would ask
+ * for. There is no "nothing suitable" case for a caller to handle, because a texture with no
+ * universally readable encoding is a broken manifest rather than a runtime condition.
+ *
+ * @param {TextureVariantSet} variants what was built for this texture
+ * @param {TextureRole|number} role what the texture is for
+ * @param {Set<GPUTextureFormat>} support what this device can sample
+ * @returns {string} the path to fetch
+ */
+export function texture_variant_select(variants, role, support) {
+    assert.defined(variants, 'variants');
+
+    for (const format of texture_format_preference(role, support)) {
+        const path = variants.path(format);
+
+        if (path !== undefined) {
+            return path;
+        }
+    }
+
+    return variants.fallback;
+}

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

@@ -1,5 +1,13 @@
 /**
- * If returns false - it means texture definitely has no alpha channel.
+ * If this returns false - it means the texture definitely has no alpha channel.
+ *
+ * Answered from the format, which knows exactly, rather than from the shape of whatever produced it.
+ * The previous version guessed from a `Sampler2D`'s `itemSize` and defaulted to `true` for everything
+ * else, so a single-channel `ArrayBuffer` image read as possibly-transparent.
+ *
+ * A false answer is a promise; a true one is only "cannot rule it out". Callers use this to skip
+ * alpha handling, so being wrong in the true direction costs a little work and being wrong in the
+ * false direction costs correctness.
  *
  * @param {ShadeTexture} texture
  * @returns {boolean}

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

@@ -1 +1 @@
-{"version":3,"file":"shade_texture_might_have_alpha.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/shade_texture_might_have_alpha.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,uEAFa,OAAO,CAqBnB"}
+{"version":3,"file":"shade_texture_might_have_alpha.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/shade_texture_might_have_alpha.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;GAaG;AACH,uEAFa,OAAO,CAmDnB"}

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

@@ -1,5 +1,40 @@
+import { gpu_texture_format_info } from "../../descriptor/texture/format/gpu_texture_format_info.js";
+import { texture_format_from_shade_image } from "./format/texture_format_from_shade_image.js";
+
 /**
- * If returns false - it means texture definitely has no alpha channel.
+ * Compressed formats with no alpha channel at all.
+ *
+ * Everything else in the BC/ETC2/ASTC families either carries alpha or may — including
+ * `bc1-rgba-unorm`, which WebGPU exposes only in its RGBA spelling and which decodes one bit of
+ * punch-through alpha. Reading BC1 as opaque is the mistake this set exists to not make.
+ *
+ * @type {Set<GPUTextureFormat>}
+ */
+const NO_ALPHA_COMPRESSED = new Set([
+    "bc4-r-unorm",
+    "bc4-r-snorm",
+    "bc5-rg-unorm",
+    "bc5-rg-snorm",
+    "bc6h-rgb-ufloat",
+    "bc6h-rgb-float",
+    "etc2-rgb8unorm",
+    "etc2-rgb8unorm-srgb",
+    "eac-r11unorm",
+    "eac-r11snorm",
+    "eac-rg11unorm",
+    "eac-rg11snorm",
+]);
+
+/**
+ * If this returns false - it means the texture definitely has no alpha channel.
+ *
+ * Answered from the format, which knows exactly, rather than from the shape of whatever produced it.
+ * The previous version guessed from a `Sampler2D`'s `itemSize` and defaulted to `true` for everything
+ * else, so a single-channel `ArrayBuffer` image read as possibly-transparent.
+ *
+ * A false answer is a promise; a true one is only "cannot rule it out". Callers use this to skip
+ * alpha handling, so being wrong in the true direction costs a little work and being wrong in the
+ * false direction costs correctness.
  *
  * @param {ShadeTexture} texture
  * @returns {boolean}
@@ -9,18 +44,48 @@ export function shade_texture_might_have_alpha(texture) {
         return false;
     }
 
-    const source = texture.image?.source;
+    const image = texture.image;
+
+    if (image === undefined || image === null || image.source === undefined || image.source === null) {
+        return false;
+    }
+
+    const source = image.source;
 
-    if (source === undefined) {
+    if (source.isShadeTexelData !== true && image.channel_count < 4) {
+        /*
+         Loose pixels with fewer than four channels. The *texture* will have an alpha channel — the
+         upload pads RGB to RGBA, because WebGPU has no three-channel format — but it is 1 everywhere
+         and the content has no transparency to speak of. Answering from the padded format would call
+         every opaque RGB image possibly-transparent.
+
+         Not asked of a texel payload: its channel count describes nothing, because whatever encoded
+         it already chose a format that says how many channels there are.
+        */
         return false;
     }
 
-    if (source.isSampler2D && source.itemSize <= 3) {
+    let format;
+
+    try {
+        format = texture_format_from_shade_image(image);
+    } catch {
+        // a source nothing can name a format for; no basis to promise there is no alpha
+        return true;
+    }
+
+    if (NO_ALPHA_COMPRESSED.has(format)) {
         return false;
     }
 
-    // TODO add support for more image types
+    const info = gpu_texture_format_info(format);
+
+    if (info.block_width !== 1 || info.block_height !== 1) {
+        // a compressed format that is not in the set above — BC7, BC1's punch-through, ETC2's
+        // RGBA and RGB8A1, every ASTC block size
+        return true;
+    }
 
-    // assume
-    return true;
-}
+    // uncompressed: the channel count is in the name, and only a four-channel format has an alpha
+    return /^(rgba|bgra)/.test(format);
+}

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

@@ -0,0 +1,27 @@
+/**
+ * What a texture's fourth channel means, and therefore what may be done to it.
+ *
+ * The renderer wants premultiplied alpha
+ * (@see https://www.realtimerendering.com/blog/gpus-prefer-premultiplication/), so an upload may have
+ * to multiply RGB by A on the way. Whether that is correct is not a property of the channel existing
+ * — it is a property of the channel *meaning opacity*. Scaling a height field, an ORM map or a LUT
+ * by its fourth channel corrupts it.
+ *
+ * Three answers rather than a boolean, because collapsing {@link Opaque } into {@link Straight } does
+ * exactly that corruption, and collapsing it into {@link Premultiplied } lies about data that was
+ * never multiplied by anything. Plus {@link Unspecified }, which is the *absence* of an answer and
+ * belongs in the enum rather than being spelled `undefined` alongside it — a field typed as this
+ * enum should only ever hold one of its members.
+ *
+ * Block-compressed data can only be {@link Premultiplied } or {@link Opaque }: nothing can multiply
+ * BC7 blocks without decoding them, so a compressed payload that declares {@link Straight } is a
+ * payload whose encoder did not do its job, and the upload says so rather than shipping fringes.
+ */
+export type AlphaMode = number;
+export namespace AlphaMode {
+    let Unspecified: number;
+    let Opaque: number;
+    let Straight: number;
+    let Premultiplied: number;
+}
+//# sourceMappingURL=AlphaMode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AlphaMode.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/source/AlphaMode.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;wBAmBU,MAAM"}

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

@@ -0,0 +1,52 @@
+/**
+ * What a texture's fourth channel means, and therefore what may be done to it.
+ *
+ * The renderer wants premultiplied alpha
+ * (@see https://www.realtimerendering.com/blog/gpus-prefer-premultiplication/), so an upload may have
+ * to multiply RGB by A on the way. Whether that is correct is not a property of the channel existing
+ * — it is a property of the channel *meaning opacity*. Scaling a height field, an ORM map or a LUT
+ * by its fourth channel corrupts it.
+ *
+ * Three answers rather than a boolean, because collapsing {@link Opaque} into {@link Straight} does
+ * exactly that corruption, and collapsing it into {@link Premultiplied} lies about data that was
+ * never multiplied by anything. Plus {@link Unspecified}, which is the *absence* of an answer and
+ * belongs in the enum rather than being spelled `undefined` alongside it — a field typed as this
+ * enum should only ever hold one of its members.
+ *
+ * Block-compressed data can only be {@link Premultiplied} or {@link Opaque}: nothing can multiply
+ * BC7 blocks without decoding them, so a compressed payload that declares {@link Straight} is a
+ * payload whose encoder did not do its job, and the upload says so rather than shipping fringes.
+ *
+ * @enum {number}
+ */
+export const AlphaMode = {
+    /**
+     * Nothing has said. Derive it — see {@link ShadeImage.alpha_mode}.
+     *
+     * The state a field starts in, and the one to assign to go back to deriving after an override.
+     * A resolved alpha mode is never this: {@link ShadeImage.alpha_mode} answers one of the three
+     * below, always.
+     */
+    Unspecified: 0,
+
+    /**
+     * There is no meaningful alpha. Never premultiply.
+     *
+     * The state of every non-colour texture: {@link ColorSpace.None} data, single- and two-channel
+     * images, anything whose fourth channel carries a value rather than an opacity.
+     */
+    Opaque: 1,
+
+    /**
+     * Colour with straight (unassociated) alpha — RGB is the colour at full opacity.
+     *
+     * Premultiplied on upload where that is possible, which for a block format it is not.
+     */
+    Straight: 2,
+
+    /**
+     * RGB has already been multiplied by A, by an offline encoder or by
+     * `copyExternalImageToTexture`. Nothing further to do.
+     */
+    Premultiplied: 3,
+};

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

@@ -1,4 +1,9 @@
 export class ShadeImage {
+    /**
+     * @param {ShadeTexelData} texel_data
+     * @returns {ShadeImage}
+     */
+    static fromTexelData(texel_data: ShadeTexelData): ShadeImage;
     /**
      *
      * @param {ImageBitmap} bitmap
@@ -58,6 +63,34 @@ export class ShadeImage {
     get height(): number;
     set depth(arg: number);
     get depth(): number;
+    set alpha_mode(arg: number);
+    /**
+     * What this image's fourth channel means — see {@link AlphaMode}.
+     *
+     * {@link AlphaMode.Unspecified} — the state this starts in — means derive it from
+     * {@link color_space}. Derived rather than captured at construction because `color_space` is
+     * routinely assigned *after* the image is built: nine places do it, `shade_load_data_image` and
+     * `gltf_create_material` among them, and two of them assign {@link ColorSpace.None}. A value
+     * frozen at construction would describe the image nobody kept, and would premultiply exactly the
+     * data textures the {@link AlphaMode.Opaque} state exists to protect.
+     *
+     * The derivation is exactly the rule the upload path used to apply inline, so nothing changes
+     * for an image that says nothing: non-colour data is never premultiplied, colour is.
+     *
+     * Assigning {@link AlphaMode.Unspecified} goes back to deriving.
+     *
+     * @returns {AlphaMode|number} never {@link AlphaMode.Unspecified} — this resolves
+     */
+    get alpha_mode(): number;
+    /**
+     * How many mip levels this image supplies.
+     *
+     * One, for everything that is not a {@link ShadeTexelData} — a bitmap or a sampler is a single
+     * level, and any others are generated.
+     *
+     * @returns {number}
+     */
+    get level_count(): number;
     hash(): number;
     /**
      *

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

@@ -1 +1 @@
-{"version":3,"file":"ShadeImage.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/source/ShadeImage.js"],"names":[],"mappings":"AASA;IAoHI;;;;OAIG;IACH,+BAHW,WAAW,GACV,UAAU,CAkBrB;IAED;;;;OAIG;IACH,0CAFY,UAAU,CAqBrB;IAED;;;;;;;;;OASG;IACH,qCARW,WAAW,iBACX,MAAM,aACN,cAAc,UACd,MAAM,WACN,MAAM,UACN,MAAM,GACL,UAAU,CAkCrB;IAxMD,iBAEC;IAED;;;OAGG;IACH,aAFU,UAAU,GAAC,MAAM,CAES;IAgBpC,2BAEC;IAVD;;;OAGG;IACH,wBAEC;IAoBD,+BAEC;IAVD;;;OAGG;IACH,4BAEC;IAMD;;;;OAIG;IACH,YAFU,OAAO,CAEC;IAelB,qBAEC;IAVD;;;OAGG;IACH,kBAEC;IAYD,uBAEC;IAND,oBAEC;IAUD,wBAEC;IAND,qBAEC;IAUD,uBAEC;IAND,oBAEC;IAMD,eAEC;IAED;;;;OAIG;IACH,cAHW,UAAU,GACR,OAAO,CAInB;IAgGL;;;OAGG;IACH,uBAFU,OAAO,CAEgB;;CANhC;2BApN0B,kBAAkB;+BAJd,gDAAgD"}
+{"version":3,"file":"ShadeImage.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/source/ShadeImage.js"],"names":[],"mappings":"AAUA;IA6JI;;;OAGG;IACH,kDAFa,UAAU,CAetB;IAeD;;;;OAIG;IACH,+BAHW,WAAW,GACV,UAAU,CAkBrB;IAED;;;;OAIG;IACH,0CAFY,UAAU,CAqBrB;IAED;;;;;;;;;OASG;IACH,qCARW,WAAW,iBACX,MAAM,aACN,cAAc,UACd,MAAM,WACN,MAAM,UACN,MAAM,GACL,UAAU,CAkCrB;IAjRD,iBAEC;IAED;;;OAGG;IACH,aAFU,UAAU,GAAC,MAAM,CAES;IAgBpC,2BAEC;IAVD;;;OAGG;IACH,wBAEC;IAoBD,+BAEC;IAVD;;;OAGG;IACH,4BAEC;IAMD;;;;OAIG;IACH,YAFU,OAAO,CAEC;IAelB,qBAEC;IAVD;;;OAGG;IACH,kBAEC;IAYD,uBAEC;IAND,oBAEC;IAUD,wBAEC;IAND,qBAEC;IAUD,uBAEC;IAND,oBAEC;IAoCD,4BAIC;IA7BD;;;;;;;;;;;;;;;;OAgBG;IACH,yBAMC;IAQD;;;;;;;OAOG;IACH,0BAQC;IAqBD,eAEC;IAED;;;;OAIG;IACH,cAHW,UAAU,GACR,OAAO,CAInB;IAgGL;;;OAGG;IACH,uBAFU,OAAO,CAEgB;;CANhC;2BA9R0B,kBAAkB;+BAJd,gDAAgD"}

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

@@ -4,6 +4,7 @@ import {
     compute_binary_data_type_from_typed_array
 } from "../../../../core/collection/array/typed/compute_binary_data_type_from_typed_array.js";
 import { ColorSpace } from "../ColorSpace.js";
+import { AlphaMode } from "./AlphaMode.js";
 
 let id_counter = 0;
 
@@ -110,6 +111,79 @@ export class ShadeImage {
         this.#size[2] = value;
     }
 
+    /**
+     * @type {AlphaMode|number}
+     */
+    #alpha_mode = AlphaMode.Unspecified;
+
+    /**
+     * What this image's fourth channel means — see {@link AlphaMode}.
+     *
+     * {@link AlphaMode.Unspecified} — the state this starts in — means derive it from
+     * {@link color_space}. Derived rather than captured at construction because `color_space` is
+     * routinely assigned *after* the image is built: nine places do it, `shade_load_data_image` and
+     * `gltf_create_material` among them, and two of them assign {@link ColorSpace.None}. A value
+     * frozen at construction would describe the image nobody kept, and would premultiply exactly the
+     * data textures the {@link AlphaMode.Opaque} state exists to protect.
+     *
+     * The derivation is exactly the rule the upload path used to apply inline, so nothing changes
+     * for an image that says nothing: non-colour data is never premultiplied, colour is.
+     *
+     * Assigning {@link AlphaMode.Unspecified} goes back to deriving.
+     *
+     * @returns {AlphaMode|number} never {@link AlphaMode.Unspecified} — this resolves
+     */
+    get alpha_mode() {
+        if (this.#alpha_mode !== AlphaMode.Unspecified) {
+            return this.#alpha_mode;
+        }
+
+        return this.color_space === ColorSpace.None ? AlphaMode.Opaque : AlphaMode.Straight;
+    }
+
+    set alpha_mode(value) {
+        assert.enum(value, AlphaMode, 'alpha_mode');
+
+        this.#alpha_mode = value;
+    }
+
+    /**
+     * How many mip levels this image supplies.
+     *
+     * One, for everything that is not a {@link ShadeTexelData} — a bitmap or a sampler is a single
+     * level, and any others are generated.
+     *
+     * @returns {number}
+     */
+    get level_count() {
+        const source = this.#source;
+
+        if (source !== undefined && source !== null && source.isShadeTexelData === true) {
+            return source.level_count;
+        }
+
+        return 1;
+    }
+
+    /**
+     * @param {ShadeTexelData} texel_data
+     * @returns {ShadeImage}
+     */
+    static fromTexelData(texel_data) {
+        assert.defined(texel_data, 'texel_data');
+        assert.equal(texel_data.isShadeTexelData, true, 'texel_data.isShadeTexelData !== true');
+
+        const r = new ShadeImage();
+
+        r.#source = texel_data;
+
+        r.#size[0] = texel_data.width;
+        r.#size[1] = texel_data.height;
+        r.#size[2] = texel_data.depth;
+
+        return r;
+    }
+
     hash() {
         return this.#id;
     }

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;