@woosh/meep-engine 3.14.1 → 3.14.3

package/src/shade/renderer/texture/encode/texture_encode_shader.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The compute shader that encodes into `format`.
+ *
+ * Refuses by name rather than approximating: a target this cannot write yet is named as such, and a
+ * format that was never a target is named as that. Nothing is encoded as a neighbour of what was
+ * asked for.
+ *
+ * @param {GPUTextureFormat} format
+ * @returns {ComputeShader}
+ * @throws {Error} naming the format, for one that is not implemented or not a target
+ */
+export function texture_encode_shader(format: GPUTextureFormat): ComputeShader;
+/**
+ * Whether the block encoder can write `format` today.
+ *
+ * @param {GPUTextureFormat} format
+ * @returns {boolean}
+ */
+export function texture_encode_implements(format: GPUTextureFormat): boolean;
+/**
+ * Every format the block encoder is meant to write, implemented or not.
+ *
+ * The list the refusal below reads, so that a target that is planned and a name that was never a
+ * target get different answers: one says "not yet", the other "not at all".
+ *
+ * @readonly
+ * @type {GPUTextureFormat[]}
+ */
+export const TEXTURE_ENCODE_TARGETS: GPUTextureFormat[];
+//# sourceMappingURL=texture_encode_shader.d.ts.map

package/src/shade/renderer/texture/encode/texture_encode_shader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture_encode_shader.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/encode/texture_encode_shader.js"],"names":[],"mappings":"AAiEA;;;;;;;;;;GAUG;AACH,+EAqBC;AAED;;;;;GAKG;AACH,qEAFa,OAAO,CAInB;AAhGD;;;;;;;;GAQG;AACH,qCAFU,kBAAkB,CAkB1B"}

package/src/shade/renderer/texture/encode/texture_encode_shader.js

@@ -0,0 +1,108 @@
+import { gpu_texture_format_info } from "../../../descriptor/texture/format/gpu_texture_format_info.js";
+import { TextureFormat } from "../../../descriptor/texture/format/TextureFormat.js";
+import { shader_texture_encode_astc_4x4 } from "./shader_texture_encode_astc_4x4.js";
+import { shader_texture_encode_bc1 } from "./shader_texture_encode_bc1.js";
+import { shader_texture_encode_bc4 } from "./shader_texture_encode_bc4.js";
+import { shader_texture_encode_bc4_snorm } from "./shader_texture_encode_bc4_snorm.js";
+import { shader_texture_encode_bc5 } from "./shader_texture_encode_bc5.js";
+import { shader_texture_encode_bc5_snorm } from "./shader_texture_encode_bc5_snorm.js";
+import { shader_texture_encode_bc6h } from "./shader_texture_encode_bc6h.js";
+import { shader_texture_encode_bc7 } from "./shader_texture_encode_bc7.js";
+
+/**
+ * Every format the block encoder is meant to write, implemented or not.
+ *
+ * The list the refusal below reads, so that a target that is planned and a name that was never a
+ * target get different answers: one says "not yet", the other "not at all".
+ *
+ * @readonly
+ * @type {GPUTextureFormat[]}
+ */
+export const TEXTURE_ENCODE_TARGETS = [
+    TextureFormat.BC1_RGBA_UNORM,
+    TextureFormat.BC1_RGBA_UNORM_SRGB,
+    TextureFormat.BC4_R_UNORM,
+    TextureFormat.BC4_R_SNORM,
+    TextureFormat.BC5_RG_UNORM,
+    TextureFormat.BC5_RG_SNORM,
+    TextureFormat.BC6H_RGB_UFLOAT,
+    TextureFormat.BC7_RGBA_UNORM,
+    TextureFormat.BC7_RGBA_UNORM_SRGB,
+    TextureFormat.ASTC_4X4_UNORM,
+    TextureFormat.ASTC_4X4_UNORM_SRGB,
+    TextureFormat.ASTC_6X6_UNORM,
+    TextureFormat.ASTC_6X6_UNORM_SRGB,
+    TextureFormat.ASTC_8X8_UNORM,
+    TextureFormat.ASTC_8X8_UNORM_SRGB,
+];
+
+/**
+ * The encoder for each implemented target.
+ *
+ * **An `-srgb` format and its linear twin are one encoder**, listed twice rather than resolved by
+ * stripping the suffix: the two are the same encoded bytes and differ only in how the sampler
+ * decodes them, so the encoder does identical work and the caller's format is the tag the texture is
+ * created with. Listing both keeps the map the whole of the answer — nothing here strips a suffix
+ * and guesses. **A `snorm` format is not a tag**: its endpoints are signed and its palette runs over
+ * a different domain, so it is its own shader.
+ *
+ * @readonly
+ * @type {Map<GPUTextureFormat, ComputeShader>}
+ */
+const ENCODERS = new Map([
+    [TextureFormat.BC1_RGBA_UNORM, shader_texture_encode_bc1],
+    [TextureFormat.BC1_RGBA_UNORM_SRGB, shader_texture_encode_bc1],
+    [TextureFormat.BC4_R_UNORM, shader_texture_encode_bc4],
+    [TextureFormat.BC4_R_SNORM, shader_texture_encode_bc4_snorm],
+    [TextureFormat.BC5_RG_UNORM, shader_texture_encode_bc5],
+    [TextureFormat.BC5_RG_SNORM, shader_texture_encode_bc5_snorm],
+    [TextureFormat.BC6H_RGB_UFLOAT, shader_texture_encode_bc6h],
+    [TextureFormat.BC7_RGBA_UNORM, shader_texture_encode_bc7],
+    [TextureFormat.BC7_RGBA_UNORM_SRGB, shader_texture_encode_bc7],
+    [TextureFormat.ASTC_4X4_UNORM, shader_texture_encode_astc_4x4],
+    [TextureFormat.ASTC_4X4_UNORM_SRGB, shader_texture_encode_astc_4x4],
+]);
+
+/**
+ * The compute shader that encodes into `format`.
+ *
+ * Refuses by name rather than approximating: a target this cannot write yet is named as such, and a
+ * format that was never a target is named as that. Nothing is encoded as a neighbour of what was
+ * asked for.
+ *
+ * @param {GPUTextureFormat} format
+ * @returns {ComputeShader}
+ * @throws {Error} naming the format, for one that is not implemented or not a target
+ */
+export function texture_encode_shader(format) {
+    // throws for a name that is not a format at all, which is the first thing worth knowing
+    gpu_texture_format_info(format);
+
+    const shader = ENCODERS.get(format);
+
+    if (shader !== undefined) {
+        return shader;
+    }
+
+    if (TEXTURE_ENCODE_TARGETS.includes(format)) {
+        throw new Error(
+            `texture_encode: '${format}' is a planned target of the block encoder and is not implemented yet.`
+            + ` Nothing approximates it; the implemented targets are ${[...ENCODERS.keys()].join(', ')}`
+        );
+    }
+
+    throw new Error(
+        `texture_encode: '${format}' is not a target of the block encoder.`
+        + ` The targets are ${TEXTURE_ENCODE_TARGETS.join(', ')}`
+    );
+}
+
+/**
+ * Whether the block encoder can write `format` today.
+ *
+ * @param {GPUTextureFormat} format
+ * @returns {boolean}
+ */
+export function texture_encode_implements(format) {
+    return ENCODERS.has(format);
+}

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

@@ -0,0 +1,17 @@
+/**
+ * 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). Which family a format belongs to is
+ * {@link gpu_texture_format_feature}'s answer, derived from the format table's own names — the same
+ * answer the software device refuses a texture by.
+ *
+ * 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":"AAGA;;;;;;;;;;;;;;GAcG;AACH,oEAFa,qBAAqB,CAgBjC"}

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

@@ -0,0 +1,33 @@
+import { gpu_texture_format_feature } from "../../../descriptor/texture/format/gpu_texture_format_feature.js";
+import { gpu_texture_format_names } from "../../../descriptor/texture/format/gpu_texture_format_info.js";
+
+/**
+ * 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). Which family a format belongs to is
+ * {@link gpu_texture_format_feature}'s answer, derived from the format table's own names — the same
+ * answer the software device refuses a texture by.
+ *
+ * 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 format of gpu_texture_format_names()) {
+        const feature = gpu_texture_format_feature(format);
+
+        if (feature !== undefined && features.has(feature)) {
+            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":"AAMA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qFAkEC"}

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

@@ -0,0 +1,95 @@
+import { BinaryDataType } from "../../../../core/binary/type/BinaryDataType.js";
+import { isImageBitmap } from "../../../../core/dom/isImageBitmap.js";
+import { gpu_texture_format_srgb } from "../../../descriptor/texture/format/gpu_texture_format_srgb.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 — but not whether sampling it decodes sRGB, which is
+         the image's business and not the payload's. `bc7-rgba-unorm` and `bc7-rgba-unorm-srgb` are
+         the same bytes, so a transcoder targeting one does exactly the work of the other and has no
+         reason to prefer either; what settles it is what the texture *means*, which is `color_space`
+         and is assigned after construction. Returning the payload's name verbatim ignored that and
+         put all 25 of Sponza's albedo maps on a linear format, sampling sRGB-encoded values as
+         though they were linear — brighter, flatter, and cold, because the decode that stretches
+         the gap between channels was the part being skipped.
+        */
+        if (image.color_space !== ColorSpace.SRGB) {
+            return source.format;
+        }
+
+        const srgb = gpu_texture_format_srgb(source.format);
+
+        if (srgb === undefined) {
+            throw new Error(
+                `image ${image.id} is sRGB but its payload is '${source.format}', which has no sRGB`
+                + ` counterpart, so the decode cannot be expressed. Transcode it to a format that`
+                + ` has one, or set color_space to something other than SRGB.`
+            );
+        }
+
+        return srgb;
+    }
+
+    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));
+}