@woosh/meep-engine 3.14.0 → 3.14.2

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

@@ -1 +1 @@
-{"version":3,"file":"TextureManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/TextureManager.js"],"names":[],"mappings":"AA2CA;IAiCI;;;OAGG;IACH,+BAIC;IAtBD;;;OAGG;IACH,qCAEC;IAkBD;;;;OAIG;IACH,6BAFa,iBAAiB,CAY7B;IAED;;;;OAIG;IACH,8CAFa,iBAAiB,CA4B7B;IAeD;;;;OAIG;IACH,kCAHW,iBAAiB,GACf,iBAAiB,CAa7B;IAED,eAEC;IAED,+BAQC;;CACJ;sCAhLqC,oCAAoC;kCADxC,wBAAwB;kCADxB,+CAA+C"}
+{"version":3,"file":"TextureManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/TextureManager.js"],"names":[],"mappings":"AA2CA;IAiCI;;;OAGG;IACH,+BAIC;IAtBD;;;OAGG;IACH,qCAEC;IAkBD;;;;OAIG;IACH,6BAFa,iBAAiB,CAY7B;IAED;;;;OAIG;IACH,8CAFa,iBAAiB,CAwC7B;IAeD;;;;OAIG;IACH,kCAHW,iBAAiB,GACf,iBAAiB,CAa7B;IAED,eAEC;IAED,+BAQC;;CACJ;sCA5LqC,oCAAoC;kCADxC,wBAAwB;kCADxB,+CAA+C"}

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

@@ -121,10 +121,22 @@ export class TextureManager {
 
             const ctx = this.contextFromDescriptor(descriptor);
 
-            // copy data into texture
-            this.#image_to_texture(shade.image, ctx.gpu_texture);
-
-            if ((shade.flags & ShadeTextureFlags.GenerateMipMaps) !== 0) {
+            /*
+             The flag is an instruction, and the descriptor builder has already refused it for any
+             format the generator cannot render into — so reaching here with it set means it is
+             going to happen. Only the base level is uploaded in that case: the generator produces
+             every level above it, and sending levels it is about to overwrite is bytes across the
+             bus for nothing.
+            */
+            const generate = (shade.flags & ShadeTextureFlags.GenerateMipMaps) !== 0;
+
+            this.#image_to_texture(
+                shade.image,
+                ctx.gpu_texture,
+                generate ? 1 : shade.image.level_count
+            );
+
+            if (generate) {
                 this.#mipmaps.schedule(ctx.gpu_texture, descriptor, shade.mipmapGenerationFilter);
             }
 
@@ -138,13 +150,13 @@ export class TextureManager {
      *
      * @param {ShadeImage} image
      * @param {GPUTexture} texture
+     * @param {number} level_count how many of the image's levels to upload
      */
-    #image_to_texture(image, texture) {
-
-
+    #image_to_texture(image, texture, level_count) {
         const device = this.#device;
         const queue = device.queue;
-        texture_write_to_gpu(image, texture, queue);
+
+        texture_write_to_gpu(image, texture, queue, level_count);
     }
 
     /**

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

@@ -0,0 +1,19 @@
+/**
+ * What a texture is *for*, as far as choosing an encoding for it goes.
+ *
+ * The renderer knows things about its material slots that no general image pipeline does: that a
+ * normal map's channels are a direction and band visibly under a codec tuned for colour, that an ORM
+ * map is linear data whose channels are independent, that albedo is the one people look at. Those
+ * facts pick a format, so they have to be sayable.
+ *
+ * The same distinction {@link image_compression_quality_from_usage } already draws for the AVIF
+ * encoder, named once instead of twice.
+ */
+export type TextureRole = number;
+export namespace TextureRole {
+    let Albedo: number;
+    let Normal: number;
+    let Orm: number;
+    let Emissive: number;
+}
+//# sourceMappingURL=TextureRole.d.ts.map

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

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

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

@@ -0,0 +1,26 @@
+/**
+ * What a texture is *for*, as far as choosing an encoding for it goes.
+ *
+ * The renderer knows things about its material slots that no general image pipeline does: that a
+ * normal map's channels are a direction and band visibly under a codec tuned for colour, that an ORM
+ * map is linear data whose channels are independent, that albedo is the one people look at. Those
+ * facts pick a format, so they have to be sayable.
+ *
+ * The same distinction {@link image_compression_quality_from_usage} already draws for the AVIF
+ * encoder, named once instead of twice.
+ *
+ * @enum {number}
+ */
+export const TextureRole = {
+    /** Base colour. sRGB, alpha may carry cutout or transparency. */
+    Albedo: 0,
+
+    /** Tangent-space normals. Linear, and the channels are a direction rather than a colour. */
+    Normal: 1,
+
+    /** Occlusion / roughness / metalness, packed per channel. Linear, channels independent. */
+    Orm: 2,
+
+    /** Emitted colour. sRGB, like albedo. */
+    Emissive: 3,
+};

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

@@ -0,0 +1,71 @@
+/**
+ * What was built for one texture, and where each encoding lives.
+ *
+ * A texture is not one resource with variants inside it — it is several resources, one per format,
+ * and a client fetches the one it wants. This is the manifest that makes that possible: **which
+ * encodings exist, known before the first request.** Discovering them by requesting would cost a 404
+ * round trip per format a device prefers and nobody built, walking down the preference list, which on
+ * a streaming engine is the worst place to put a stall.
+ *
+ * The {@link fallback} is not a contingency bolted on; it is the entry with no format constraint, and
+ * it is what a device with no compression support, a tool, or a test asks for. Every set has one, so
+ * selection always has an answer.
+ *
+ * Deliberately dumb about *content*: it says a format was built and where the bytes are, and nothing
+ * about what they decode to. The reader determines that from the payload's own header, which is why
+ * a manifest that lies produces a failed read rather than a texture full of garbage.
+ */
+export class TextureVariantSet {
+    /**
+     * Read one entry of a manifest.
+     *
+     * ```json
+     * {
+     *   "fallback": "textures/wall_albedo.avif",
+     *   "formats": {
+     *     "bc7-rgba-unorm": "textures/wall_albedo.bc7.ktx2",
+     *     "astc-4x4-unorm": "textures/wall_albedo.astc.ktx2"
+     *   }
+     * }
+     * ```
+     *
+     * Format names are the WebGPU strings, and 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
+     * listed here — it is chosen when the texture is created, from the image's colour space.
+     *
+     * @param {{fallback: string, formats?: Object<GPUTextureFormat, string>}} json
+     * @returns {TextureVariantSet}
+     */
+    static fromJSON(json: {
+        fallback: string;
+        formats?: any;
+    }): TextureVariantSet;
+    /**
+     * @param {string} fallback path of the universally readable encoding
+     * @param {Iterable<[GPUTextureFormat, string]>} by_format one entry per format that was built
+     */
+    constructor(fallback: string, by_format: Iterable<[GPUTextureFormat, string]>);
+    /**
+     * Path of the encoding every device can read — AVIF, PNG, whatever ships.
+     *
+     * @type {string}
+     * @readonly
+     */
+    readonly fallback: string;
+    /**
+     * @param {GPUTextureFormat} format
+     * @returns {boolean} whether this encoding was built
+     */
+    has(format: GPUTextureFormat): boolean;
+    /**
+     * @param {GPUTextureFormat} format
+     * @returns {string|undefined} where it lives, or nothing when it was not built
+     */
+    path(format: GPUTextureFormat): string | undefined;
+    /**
+     * @returns {GPUTextureFormat[]} every format built for this texture, fallback excluded
+     */
+    get formats(): GPUTextureFormat[];
+    #private;
+}
+//# sourceMappingURL=TextureVariantSet.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TextureVariantSet.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/TextureVariantSet.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH;IA0DI;;;;;;;;;;;;;;;;;;;OAmBG;IACH,sBAHW;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,MAAkC;KAAC,GAC5D,iBAAiB,CAO7B;IArED;;;OAGG;IACH,sBAHW,MAAM,aACN,SAAS,mBAAmB,MAAM,CAAC,CAAC,EAiB9C;IAhCD;;;;;OAKG;IACH,mBAHU,MAAM,CAGP;IA4BT;;;OAGG;IACH,+BAFa,OAAO,CAInB;IAED;;;OAGG;IACH,gCAFa,MAAM,GAAC,SAAS,CAI5B;IAED;;OAEG;IACH,kCAEC;;CA4BJ"}

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

@@ -0,0 +1,105 @@
+import { assert } from "../../../core/assert.js";
+import { gpu_texture_format_info } from "../../descriptor/texture/format/gpu_texture_format_info.js";
+
+/**
+ * What was built for one texture, and where each encoding lives.
+ *
+ * A texture is not one resource with variants inside it — it is several resources, one per format,
+ * and a client fetches the one it wants. This is the manifest that makes that possible: **which
+ * encodings exist, known before the first request.** Discovering them by requesting would cost a 404
+ * round trip per format a device prefers and nobody built, walking down the preference list, which on
+ * a streaming engine is the worst place to put a stall.
+ *
+ * The {@link fallback} is not a contingency bolted on; it is the entry with no format constraint, and
+ * it is what a device with no compression support, a tool, or a test asks for. Every set has one, so
+ * selection always has an answer.
+ *
+ * Deliberately dumb about *content*: it says a format was built and where the bytes are, and nothing
+ * about what they decode to. The reader determines that from the payload's own header, which is why
+ * a manifest that lies produces a failed read rather than a texture full of garbage.
+ */
+export class TextureVariantSet {
+    /**
+     * Path of the encoding every device can read — AVIF, PNG, whatever ships.
+     *
+     * @type {string}
+     * @readonly
+     */
+    fallback;
+
+    /**
+     * @type {Map<GPUTextureFormat, string>}
+     */
+    #by_format = new Map();
+
+    /**
+     * @param {string} fallback path of the universally readable encoding
+     * @param {Iterable<[GPUTextureFormat, string]>} by_format one entry per format that was built
+     */
+    constructor(fallback, by_format) {
+        assert.isString(fallback, 'fallback');
+        assert.defined(by_format, 'by_format');
+
+        for (const [format, path] of by_format) {
+            // throws for a name that is not a GPUTextureFormat — a manifest naming one is a build
+            // artefact nobody can ask for, and finding that out here beats finding it out at a fetch
+            gpu_texture_format_info(format);
+
+            assert.isString(path, `path for '${format}'`);
+
+            this.#by_format.set(format, path);
+        }
+
+        this.fallback = fallback;
+    }
+
+    /**
+     * @param {GPUTextureFormat} format
+     * @returns {boolean} whether this encoding was built
+     */
+    has(format) {
+        return this.#by_format.has(format);
+    }
+
+    /**
+     * @param {GPUTextureFormat} format
+     * @returns {string|undefined} where it lives, or nothing when it was not built
+     */
+    path(format) {
+        return this.#by_format.get(format);
+    }
+
+    /**
+     * @returns {GPUTextureFormat[]} every format built for this texture, fallback excluded
+     */
+    get formats() {
+        return Array.from(this.#by_format.keys());
+    }
+
+    /**
+     * Read one entry of a manifest.
+     *
+     * ```json
+     * {
+     *   "fallback": "textures/wall_albedo.avif",
+     *   "formats": {
+     *     "bc7-rgba-unorm": "textures/wall_albedo.bc7.ktx2",
+     *     "astc-4x4-unorm": "textures/wall_albedo.astc.ktx2"
+     *   }
+     * }
+     * ```
+     *
+     * Format names are the WebGPU strings, and 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
+     * listed here — it is chosen when the texture is created, from the image's colour space.
+     *
+     * @param {{fallback: string, formats?: Object<GPUTextureFormat, string>}} json
+     * @returns {TextureVariantSet}
+     */
+    static fromJSON(json) {
+        assert.defined(json, 'json');
+        assert.isString(json.fallback, 'json.fallback');
+
+        return new TextureVariantSet(json.fallback, Object.entries(json.formats ?? {}));
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"download_texture_data.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/download_texture_data.js"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,kGAFa,mBAAmB,CAsH/B"}
+{"version":3,"file":"download_texture_data.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/download_texture_data.js"],"names":[],"mappings":"AASA;;;;;;;;;GASG;AACH,kGAFa,mBAAmB,CAwI/B"}

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

@@ -1,6 +1,10 @@
 import { assert } from "../../../core/assert.js";
 import { round_up } from "../../../core/math/round_up.js";
 import { decode_typed_gpu_data } from "./format/decode_typed_gpu_data.js";
+import {
+    gpu_texture_format_info,
+    gpu_texture_format_is_block_compressed
+} from "../../descriptor/texture/format/gpu_texture_format_info.js";
 import { parse_gpu_texture_format } from "../../descriptor/texture/format/parse_gpu_texture_format.js";
 
 /**
@@ -61,6 +65,24 @@ export async function download_texture_data({
         label: "Download Texture Data"
     });
 
+    /*
+     Readback decodes texels into typed array elements, which a block-compressed format has none of —
+     `parse_gpu_texture_format`'s expression cannot parse one of their names and would fail with a
+     regex error naming nothing. Say what is actually wrong instead.
+
+     Not an oversight to fix later: there is no useful decoded form of a BC7 block on the CPU short of
+     a decoder, and a caller that wants the bytes wants `copyTextureToBuffer` rather than this.
+    */
+    const format_info = gpu_texture_format_info(source.format);
+
+    if (gpu_texture_format_is_block_compressed(source.format)) {
+        throw new Error(
+            `download_texture_data: '${source.format}' is block-compressed`
+            + ` (${format_info.block_width}x${format_info.block_height}), which has no per-texel`
+            + ` value to read back. Copy the raw blocks with copyTextureToBuffer instead.`
+        );
+    }
+
     // figure out data type
     const spec = parse_gpu_texture_format(source.format);
 

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

@@ -0,0 +1,15 @@
+/**
+ * Every compressed {@link GPUTextureFormat} this device can sample.
+ *
+ * WebGPU gates compression behind three optional features, all of them all-or-nothing within their
+ * family. This turns "which features did we get" into "which formats may we ask the network for",
+ * which is the question the asset layer actually has (§5).
+ *
+ * Empty is an ordinary answer, not a failure: a device with no compression support loads every scene
+ * through the uncompressed encoding, exactly as one did before any of this existed.
+ *
+ * @param {GPUDevice} device
+ * @returns {Set<GPUTextureFormat>}
+ */
+export function gpu_texture_compression_support(device: GPUDevice): Set<GPUTextureFormat>;
+//# sourceMappingURL=gpu_texture_compression_support.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_texture_compression_support.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/format/gpu_texture_compression_support.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;GAYG;AACH,oEAFa,qBAAqB,CAoBjC"}

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

@@ -0,0 +1,50 @@
+import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
+import { gpu_texture_format_names } from "../../../descriptor/texture/format/gpu_texture_format_info.js";
+
+/**
+ * Which compressed formats a feature name brings with it.
+ *
+ * Derived from the format table's own names rather than listed, because the three families partition
+ * it cleanly by prefix and a hand-written list is one more thing to forget a format from.
+ *
+ * @type {[GPUFeatureName, RegExp][]}
+ */
+const FAMILIES = [
+    [WebGPUExtensionType.TextureCompressionBC, /^bc[0-9]/],
+    // ETC2 and EAC arrive together, under one feature
+    [WebGPUExtensionType.TextureCompressionETC2, /^(etc2|eac)-/],
+    [WebGPUExtensionType.TextureCompressionASTC, /^astc-/],
+];
+
+/**
+ * Every compressed {@link GPUTextureFormat} this device can sample.
+ *
+ * WebGPU gates compression behind three optional features, all of them all-or-nothing within their
+ * family. This turns "which features did we get" into "which formats may we ask the network for",
+ * which is the question the asset layer actually has (§5).
+ *
+ * Empty is an ordinary answer, not a failure: a device with no compression support loads every scene
+ * through the uncompressed encoding, exactly as one did before any of this existed.
+ *
+ * @param {GPUDevice} device
+ * @returns {Set<GPUTextureFormat>}
+ */
+export function gpu_texture_compression_support(device) {
+    const features = device.features;
+
+    const supported = new Set();
+
+    for (const [feature, pattern] of FAMILIES) {
+        if (!features.has(feature)) {
+            continue;
+        }
+
+        for (const format of gpu_texture_format_names()) {
+            if (pattern.test(format)) {
+                supported.add(format);
+            }
+        }
+    }
+
+    return supported;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Whether {@link WebGPUMipmapGenerator} can produce this format's mip levels.
+ *
+ * It generates by *rendering* between mip levels, so the question is whether the format can be a
+ * colour attachment. Three classes cannot:
+ *
+ *  1. **Block-compressed.** BC, ETC2 and ASTC are neither render attachments nor storage bindings,
+ *     and nothing on the device turns a BC7 base level into BC7 mips. Their mips come from whatever
+ *     encoded them, and that is the case this predicate exists for.
+ *  2. **Depth and stencil.** Renderable, but not as *colour*, which is what the generator's pipeline
+ *     writes.
+ *  3. **`snorm`, and `rgb9e5ufloat`.** Sampleable colour formats that WebGPU does not allow as
+ *     attachments — a gap that predates compressed textures and would otherwise surface as a
+ *     pipeline-creation failure deep inside the generator.
+ *
+ * **Not a general renderability table.** Anything outside those three classes answers `true`, which
+ * is right for every format the engine currently produces and is not a promise about exotic ones —
+ * `rg11b10ufloat` is renderable only with a feature enabled, and this does not check for it. The
+ * value of answering here rather than in `createRenderPipeline` is a message that names the texture
+ * and says what to do instead.
+ *
+ * @param {GPUTextureFormat} format
+ * @returns {boolean}
+ * @throws {Error} for a name that is not a GPUTextureFormat
+ */
+export function gpu_texture_format_can_generate_mipmaps(format: GPUTextureFormat): boolean;
+//# sourceMappingURL=gpu_texture_format_can_generate_mipmaps.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_texture_format_can_generate_mipmaps.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/format/gpu_texture_format_can_generate_mipmaps.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,mFAHa,OAAO,CAiBnB"}

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

@@ -0,0 +1,65 @@
+import {
+    gpu_texture_format_info,
+    gpu_texture_format_is_block_compressed
+} from "../../../descriptor/texture/format/gpu_texture_format_info.js";
+
+/**
+ * Formats that are colour formats and still cannot be a render attachment.
+ *
+ * Every `snorm` format, plus the shared-exponent packed one. Listed rather than matched on the name
+ * for the reason {@link gpu_texture_format_info} gives about its own table — though here the name
+ * would in fact carry it, a name-shaped rule invites the next entry to be added by pattern instead of
+ * by specification.
+ *
+ * @type {Set<GPUTextureFormat>}
+ */
+const NOT_RENDERABLE = new Set([
+    "r8snorm",
+    "rg8snorm",
+    "rgba8snorm",
+    "r16snorm",
+    "rg16snorm",
+    "rgba16snorm",
+    "rgb9e5ufloat",
+]);
+
+/**
+ * Whether {@link WebGPUMipmapGenerator} can produce this format's mip levels.
+ *
+ * It generates by *rendering* between mip levels, so the question is whether the format can be a
+ * colour attachment. Three classes cannot:
+ *
+ *  1. **Block-compressed.** BC, ETC2 and ASTC are neither render attachments nor storage bindings,
+ *     and nothing on the device turns a BC7 base level into BC7 mips. Their mips come from whatever
+ *     encoded them, and that is the case this predicate exists for.
+ *  2. **Depth and stencil.** Renderable, but not as *colour*, which is what the generator's pipeline
+ *     writes.
+ *  3. **`snorm`, and `rgb9e5ufloat`.** Sampleable colour formats that WebGPU does not allow as
+ *     attachments — a gap that predates compressed textures and would otherwise surface as a
+ *     pipeline-creation failure deep inside the generator.
+ *
+ * **Not a general renderability table.** Anything outside those three classes answers `true`, which
+ * is right for every format the engine currently produces and is not a promise about exotic ones —
+ * `rg11b10ufloat` is renderable only with a feature enabled, and this does not check for it. The
+ * value of answering here rather than in `createRenderPipeline` is a message that names the texture
+ * and says what to do instead.
+ *
+ * @param {GPUTextureFormat} format
+ * @returns {boolean}
+ * @throws {Error} for a name that is not a GPUTextureFormat
+ */
+export function gpu_texture_format_can_generate_mipmaps(format) {
+    const info = gpu_texture_format_info(format);
+
+    if (gpu_texture_format_is_block_compressed(format)) {
+        // block-compressed: no attachment, no storage, no way to write a mip on the device
+        return false;
+    }
+
+    if (info.aspects.length !== 1 || info.aspects[0] !== "all") {
+        // depth and/or stencil — not a colour attachment
+        return false;
+    }
+
+    return !NOT_RENDERABLE.has(format);
+}

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

@@ -0,0 +1,11 @@
+/**
+ * @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;
+import { BinaryDataType } from "../../../../core/binary/type/BinaryDataType.js";
+import { ColorSpace } from "../ColorSpace.js";
+//# sourceMappingURL=infer_format_from_parameters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"infer_format_from_parameters.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/format/infer_format_from_parameters.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,4DANW,MAAM,aACN,cAAc,cACd,OAAO,eACP,UAAU,oBA6EpB;+BArF8B,gDAAgD;2BAEpD,kBAAkB"}

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

@@ -0,0 +1,88 @@
+import { BinaryDataType } from "../../../../core/binary/type/BinaryDataType.js";
+import { dataTypeByteSize } from "../../../../core/binary/type/DataTypeByteSizes.js";
+import { ColorSpace } from "../ColorSpace.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}`;
+}
+
+

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

@@ -0,0 +1,24 @@
+/**
+ * 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: ShadeImage): GPUTextureFormat;
+//# sourceMappingURL=texture_format_from_shade_image.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"texture_format_from_shade_image.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/format/texture_format_from_shade_image.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qFA2CC"}