@woosh/meep-engine 3.14.0 → 3.14.2

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

@@ -0,0 +1,71 @@
+import { BinaryDataType } from "../../../../core/binary/type/BinaryDataType.js";
+import { isImageBitmap } from "../../../../core/dom/isImageBitmap.js";
+import { ColorSpace } from "../ColorSpace.js";
+import { infer_format_from_parameters } from "./infer_format_from_parameters.js";
+
+/**
+ * The {@link GPUTextureFormat} a {@link ShadeImage}'s texels are in.
+ *
+ * A free function rather than a getter on the image, because {@link ShadeImage} describes *data* —
+ * a channel count, a data type, a colour space, some bytes — and what WebGPU calls that arrangement
+ * is not the data's business. The image stays a model the encoder, the container readers and the
+ * asset pipeline can hold without any of them importing a graphics API.
+ *
+ * What this replaces is the same inference run at *upload* time, inside the descriptor builder. The
+ * move matters more than the mechanism: a format worked out by inspecting pixels is a question
+ * block-compressed texels cannot answer, so a {@link ShadeTexelData} states its format instead and
+ * this function simply reports it. That is what lets both kinds share one path.
+ *
+ * **Not cached anywhere.** `color_space` is assigned *after* construction in nine places
+ * (`gltf_create_material` among them), so a format captured once would leave every glTF albedo map
+ * on `rgba8unorm` and silently drop its sRGB decode.
+ *
+ * @param {ShadeImage} image
+ * @returns {GPUTextureFormat}
+ * @throws {Error} if the image has no source, or one this does not recognise — a format guessed for
+ * texels nobody can describe would put the wrong number of bytes on both sides of the upload
+ */
+export function texture_format_from_shade_image(image) {
+    const source = image.source;
+
+    if (source === undefined || source === null) {
+        throw new Error(`image ${image.id} has no source, so no format`);
+    }
+
+    if (source.isShadeTexelData === true) {
+        // already in a GPU format; it says which
+        return source.format;
+    }
+
+    if (source.isSampler2D === true) {
+        return infer_format_from_parameters(
+            image.channel_count, image.data_type, image.normalized, image.color_space
+        );
+    }
+
+    if (isImageBitmap(source)) {
+        /*
+         A bitmap is whatever the browser decoded it to, which is 8-bit RGBA — the channel count and
+         data type the image carries describe the file, not the decode.
+        */
+        if (image.data_type === BinaryDataType.Float16) {
+            return "rgba16float";
+        }
+
+        if (image.color_space === ColorSpace.SRGB) {
+            // sampling decodes sRGB to linear for free
+            // @see https://www.w3.org/TR/webgpu/#texture-formats
+            return "rgba8unorm-srgb";
+        }
+
+        return "rgba8unorm";
+    }
+
+    if (source instanceof ArrayBuffer) {
+        return infer_format_from_parameters(
+            image.channel_count, image.data_type, image.normalized, image.color_space
+        );
+    }
+
+    throw new Error(`Unsupported image data`);
+}

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

@@ -0,0 +1,22 @@
+/**
+ * The formats this engine would choose for `role`, best first, filtered to what the device can
+ * sample.
+ *
+ * This is the whole of the engine's part in choosing an encoding. It answers *what would be good*;
+ * it does not fetch, does not know what was actually built for a given texture, and does not fall
+ * back — all of which belong to the asset layer, which turns an entry into a request and reaches for
+ * an uncompressed encoding when none of these can be had.
+ *
+ * **Names are the non-srgb ones.** `bc7-rgba-unorm` and `bc7-rgba-unorm-srgb` are the same bytes, so
+ * srgb-ness is not a property of the encoding to be chosen here — it is picked when the texture is
+ * created, from the image's colour space.
+ *
+ * @param {TextureRole|number} role
+ * @param {Set<GPUTextureFormat>} support what this device can sample — see
+ * {@link gpu_texture_compression_support}
+ * @returns {GPUTextureFormat[]} best first; empty when the device can sample none of them, which is
+ * an ordinary answer and means "ask for the uncompressed encoding"
+ */
+export function texture_format_preference(role: TextureRole | number, support: Set<GPUTextureFormat>): GPUTextureFormat[];
+import { TextureRole } from "../TextureRole.js";
+//# sourceMappingURL=texture_format_preference.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"texture_format_preference.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/format/texture_format_preference.js"],"names":[],"mappings":"AA8DA;;;;;;;;;;;;;;;;;;GAkBG;AACH,gDANW,WAAW,GAAC,MAAM,WAClB,qBAAqB,GAEnB,kBAAkB,CAU9B;4BAtF2B,mBAAmB"}

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

@@ -0,0 +1,89 @@
+import { assert } from "../../../../core/assert.js";
+import { TextureFormat } from "../../../descriptor/texture/format/TextureFormat.js";
+import { TextureRole } from "../TextureRole.js";
+
+/**
+ * Colour with alpha, best first. Albedo and emissive both want this.
+ *
+ * BC7 is the best quality-per-byte the desktop family offers for four channels; ASTC 4×4 matches its
+ * 8 bits per texel on mobile; ETC2's RGBA8 is the last resort for a device with neither.
+ *
+ * @type {GPUTextureFormat[]}
+ */
+const COLOR = [
+    TextureFormat.BC7_RGBA_UNORM,
+    TextureFormat.ASTC_4X4_UNORM,
+    TextureFormat.ETC2_RGBA8UNORM,
+];
+
+/**
+ * Tangent-space normals, best first.
+ *
+ * **Two channels, wherever they can be had.** A tangent-space normal's Z is positive by construction,
+ * so {@link chunk_decode_tangent_normal} reconstructs it from XY and the blue channel of a normal map
+ * carries nothing. `bc5-rg-unorm` therefore spends on two channels the same 8 bits per texel that BC7
+ * spends on four, and `eac-rg11unorm` does the same with 11 bits per channel — both are dramatically
+ * better here than a colour codec, which is what makes BC1 or BC7 normals band visibly.
+ *
+ * ASTC has no two-channel format; its 4×4 block stores XY in RG and the decode ignores the rest.
+ *
+ * @type {GPUTextureFormat[]}
+ */
+const NORMAL = [
+    TextureFormat.BC5_RG_UNORM,
+    TextureFormat.ASTC_4X4_UNORM,
+    TextureFormat.EAC_RG11UNORM,
+];
+
+/**
+ * Packed linear data — occlusion, roughness, metalness.
+ *
+ * The channels are independent quantities rather than a colour, so a codec's cross-channel
+ * correlation buys nothing; the reason to prefer BC7 anyway is that it spends its bits per channel
+ * rather than on a shared endpoint line, which is what BC1 gets wrong here.
+ *
+ * @type {GPUTextureFormat[]}
+ */
+const ORM = [
+    TextureFormat.BC7_RGBA_UNORM,
+    TextureFormat.ASTC_4X4_UNORM,
+    TextureFormat.ETC2_RGBA8UNORM,
+];
+
+/**
+ * @type {Object<TextureRole, GPUTextureFormat[]>}
+ */
+const BY_ROLE = {
+    [TextureRole.Albedo]: COLOR,
+    [TextureRole.Emissive]: COLOR,
+    [TextureRole.Normal]: NORMAL,
+    [TextureRole.Orm]: ORM,
+};
+
+/**
+ * The formats this engine would choose for `role`, best first, filtered to what the device can
+ * sample.
+ *
+ * This is the whole of the engine's part in choosing an encoding. It answers *what would be good*;
+ * it does not fetch, does not know what was actually built for a given texture, and does not fall
+ * back — all of which belong to the asset layer, which turns an entry into a request and reaches for
+ * an uncompressed encoding when none of these can be had.
+ *
+ * **Names are the non-srgb ones.** `bc7-rgba-unorm` and `bc7-rgba-unorm-srgb` are the same bytes, so
+ * srgb-ness is not a property of the encoding to be chosen here — it is picked when the texture is
+ * created, from the image's colour space.
+ *
+ * @param {TextureRole|number} role
+ * @param {Set<GPUTextureFormat>} support what this device can sample — see
+ * {@link gpu_texture_compression_support}
+ * @returns {GPUTextureFormat[]} best first; empty when the device can sample none of them, which is
+ * an ordinary answer and means "ask for the uncompressed encoding"
+ */
+export function texture_format_preference(role, support) {
+    assert.enum(role, TextureRole, 'role');
+    assert.defined(support, 'support');
+
+    const preferred = BY_ROLE[role];
+
+    return preferred.filter(format => support.has(format));
+}

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