@woosh/meep-engine 3.14.1 → 3.14.3

package/src/shade/playground/basis_textures/main.js

@@ -0,0 +1,351 @@
+import Vector3 from "../../../core/geom/Vector3.js";
+import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+import { camera_frame_sphere } from "../../renderer/camera/camera_frame_sphere.js";
+import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
+import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
+import { create_frame_loop } from "../../renderer/create_frame_loop.js";
+import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { load_gltf } from "../../renderer/loader/gltf/load_gltf.js";
+import { Renderer } from "../../renderer/Renderer.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { gpu_texture_compression_support } from "../../renderer/texture/format/gpu_texture_compression_support.js";
+import { load_default_environment } from "../load_default_environment.js";
+import { make_playground_asset_manager } from "../make_playground_asset_manager.js";
+import { texture_inventory } from "./texture_inventory.js";
+
+/**
+ * The same scene, once as JPEG and once as KTX2/Basis, with the VRAM each costs.
+ *
+ * **The tier no device-free test can reach.** Everything below this runs without a GPU: the
+ * transcoders are checked against the reference encoder's own output, the container reader against
+ * synthesised and real files, the format table against itself. What none of that can answer is
+ * whether a transcoded texture is a *texture* — whether `createTexture` accepts the format, whether
+ * `writeTexture` accepts the block-aligned row layout, and whether what appears on screen is the
+ * picture rather than noise that happens to be the right size.
+ *
+ * And the number this page exists for is the one §6.1 made honest: the same scene at roughly a
+ * quarter of the texture memory. That is the whole argument for the feature, and until a device
+ * reports it it is arithmetic rather than a measurement.
+ *
+ * Runs under the dev server (`npm run dev`), which serves `test_assets/` and resolves the one bare
+ * specifier the renderer reaches for.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * The stock model, textured with JPEGs the browser decodes to RGBA8.
+ *
+ * Served by the dev server out of `test_assets/`, which is gitignored — see `test_assets/README.md`
+ * for how to put it there.
+ *
+ * @type {string}
+ */
+const JPEG_URL = '/test_assets/Sponza/glTF/Sponza.gltf';
+
+/**
+ * The same model with every texture re-encoded to KTX2/Basis and every texture pointed at it through
+ * `KHR_texture_basisu`. Built by `make_basis_gltf.mjs` beside this file.
+ *
+ * @type {string}
+ */
+const BASIS_URL = '/test_assets/Sponza_basis/Sponza.gltf';
+
+/**
+ * @param {string} id
+ * @returns {HTMLElement}
+ */
+function element(id) {
+    return document.getElementById(id);
+}
+
+/**
+ * @param {number} bytes
+ * @returns {string}
+ */
+function mib(bytes) {
+    return `${(bytes / 1048576).toFixed(1)} MiB`;
+}
+
+/**
+ * The support sets the page can pretend the device has.
+ *
+ * **Forcing a narrower set than the device reports is the point.** The loader chooses a transcode
+ * target by intersecting what the engine wants for a texture's role with what the device can sample,
+ * and the only way to watch that choice happen — rather than read it in a function — is to lie about
+ * the device and see the formats change. `none` is the floor rather than a gap: every compressed
+ * format is an optional WebGPU feature, so the scene has to load without one, and does — as rgba8,
+ * at four bytes a texel and the same cost as the JPEGs.
+ *
+ * @param {Set<GPUTextureFormat>} device_support
+ * @returns {Object<string, Set<GPUTextureFormat>>}
+ */
+function support_choices(device_support) {
+    return {
+        device: device_support,
+        bc7_only: new Set(['bc7-rgba-unorm']),
+        bc1_only: new Set(['bc1-rgba-unorm']),
+        none: new Set(),
+    };
+}
+
+/**
+ * Stand the page up. Called by the page rather than run on import, so nothing here touches the DOM
+ * until there is one.
+ *
+ * @returns {Promise<void>}
+ */
+export async function start() {
+    const status_element = element('status');
+    const report_element = element('report');
+
+    /**
+     * @param {string} text
+     * @param {string} [kind]
+     */
+    function set_status(text, kind = '') {
+        status_element.textContent = text;
+        status_element.className = kind;
+    }
+
+    const canvas = element('view');
+
+    const context = canvas.getContext('webgpu');
+
+    if (context === null) {
+        set_status('no WebGPU context — this browser has none, or the page is not a secure context', 'fail');
+
+        return;
+    }
+
+    const renderer = new Renderer();
+
+    set_status('acquiring a device…');
+
+    await renderer.initialize({ context });
+
+    const device_support = gpu_texture_compression_support(renderer.graphics.device);
+
+    const bc = [...device_support].filter(format => format.startsWith('bc'));
+
+    element('device').textContent = device_support.size === 0
+        ? 'no compressed formats — every texture will land on the rgba8 floor'
+        : `${device_support.size} compressed formats, ${bc.length} of them BC`;
+
+    const camera = new PerspectiveCamera();
+
+    camera.transform.position.set(0, 2, -5);
+    camera.transform.lookAt(Vector3.zero);
+
+    camera.near = 0.1;
+    camera.far = 200;
+    camera.fov = 72 * DEG_TO_RAD;
+    camera.aspect = renderer.aspect_ratio;
+
+    const scene = new Scene();
+
+    // Sponza carries no light of its own, and an unlit scene tells you nothing about a texture.
+    scene.lights.add(make_sunlight({ intensity: 7.2 }));
+
+    // document.body rather than the canvas: the controller starts a keyboard device, and only a
+    // focusable element can receive key events — body carries tabindex for exactly that.
+    const controller = new OrbitalCameraController(camera, document.body);
+
+    // handy from the console
+    globalThis.renderer = renderer;
+    globalThis.scene = scene;
+    globalThis.camera = camera;
+
+    const choices = support_choices(device_support);
+
+    /**
+     * What each variant cost, so the two can be compared once both have been loaded.
+     *
+     * @type {Map<string, {count: number, formats: Map<string, object>, bytes: number, load_ms: number}>}
+     */
+    const measured = new Map();
+
+    /**
+     * The roots of whatever is in the scene, so the next load can take them back out.
+     *
+     * @type {Node3D[]}
+     */
+    let loaded_roots = [];
+
+    /**
+     * Load one variant into an emptied scene and record what its textures cost.
+     *
+     * @param {string} label
+     * @param {string} url
+     * @param {Set<GPUTextureFormat>} texture_support
+     * @returns {Promise<void>}
+     */
+    async function measure(label, url, texture_support) {
+        set_status(`loading ${label}…`);
+
+        scene.remove(loaded_roots);
+        loaded_roots = [];
+
+        const started = performance.now();
+
+        let bundle;
+
+        try {
+            bundle = await load_gltf(url, {
+                assetManager: await make_playground_asset_manager(),
+                texture_support,
+            });
+        } catch (error) {
+            set_status(`${label}: ${error.message}`, 'fail');
+
+            report_element.textContent = String(error.stack ?? error.message);
+
+            console.error(error);
+
+            return;
+        }
+
+        const load_ms = performance.now() - started;
+
+        scene.add(bundle.scenes);
+        loaded_roots = bundle.scenes;
+
+        const bounds = scene.instances.bounding_box;
+
+        camera_frame_sphere(
+            controller,
+            Math.hypot(bounds.width, bounds.height, bounds.depth) * 0.5,
+            new Vector3(bounds.centerX, bounds.centerY, bounds.centerZ)
+        );
+
+        controller.movement_speed_scale = Math.max(bounds.width, bounds.height, bounds.depth) * 0.1;
+
+        const inventory = texture_inventory(bundle.scenes);
+
+        /*
+         Upload every texture explicitly rather than letting the first frame do it.
+
+         `obtain` is the same call the renderer makes, and this is the moment the device either
+         accepts a transcoded payload or does not: `createTexture` with a block format, and
+         `writeTexture` with the block-aligned row layout the container's mip chain implies. Driving
+         it from here rather than from `render` is what makes the number below a measurement of the
+         scene rather than of whatever happened to survive frustum culling on frame one — and it puts
+         the failure, if there is one, on the texture that caused it instead of inside a frame.
+        */
+        const failures = [];
+
+        /*
+         The manager's total, not this scene's — taking a scene back out of the graph does not evict
+         its textures, so the second load reads as the sum of both. The difference across the upload
+         is what this scene costs, and it is exact because the two loads share no cache entry: the
+         key is the image's `id`, which is a per-instance counter, and every load builds fresh
+         `ShadeImage`s. Two loads of the same file are two entries, not one.
+
+         Reading the total and calling it the scene's is a mistake that flatters the comparison —
+         it inflates whichever variant is measured second, which is the one being argued for. It
+         read 5.00x that way before the difference was taken.
+        */
+        const before = renderer.graphics.textures.gpu_memory_usage;
+
+        for (const texture of inventory.textures) {
+            try {
+                renderer.graphics.textures.obtain(texture);
+            } catch (error) {
+                failures.push(error.message);
+            }
+        }
+
+        measured.set(label, {
+            ...inventory,
+            bytes: renderer.graphics.textures.gpu_memory_usage - before,
+            load_ms,
+            failures,
+        });
+
+        renderer.indicate_view_change();
+
+        if (failures.length > 0) {
+            set_status(`${label}: ${failures.length} of ${inventory.textures.length} textures would not upload`, 'fail');
+        } else {
+            set_status(
+                `${label}: ${mib(measured.get(label).bytes)} across ${inventory.count} textures`,
+                'pass'
+            );
+        }
+
+        write_report();
+    }
+
+    /**
+     * Render everything measured so far.
+     */
+    function write_report() {
+        const lines = [];
+
+        for (const [label, entry] of measured) {
+            lines.push(label);
+            lines.push(`  load          ${entry.load_ms.toFixed(0)} ms`);
+            lines.push(`  textures      ${entry.count}`);
+            lines.push(`  gpu memory    ${mib(entry.bytes)}`);
+
+            const formats = [...entry.formats].sort((a, b) => b[1].count - a[1].count);
+
+            for (const [format, format_entry] of formats) {
+                const slots = [...format_entry.slots].sort().join(', ');
+
+                lines.push(`    ${format.padEnd(18)} ${String(format_entry.count).padStart(3)}   ${slots}`);
+            }
+
+            for (const failure of entry.failures.slice(0, 3)) {
+                lines.push(`  ! ${failure}`);
+            }
+
+            lines.push('');
+        }
+
+        const jpeg = measured.get('jpeg');
+        const basis = [...measured].find(([label]) => label.startsWith('basis'));
+
+        if (jpeg !== undefined && basis !== undefined && basis[1].bytes > 0) {
+            lines.push(`${basis[0]} against jpeg`);
+            lines.push(`  ${mib(jpeg.bytes)} -> ${mib(basis[1].bytes)}`);
+            lines.push(`  ${(jpeg.bytes / basis[1].bytes).toFixed(2)}x less texture memory`);
+        }
+
+        report_element.textContent = lines.join('\n');
+    }
+
+    element('load_jpeg').addEventListener('click', () => {
+        measure('jpeg', JPEG_URL, device_support).catch(error => console.error(error));
+    });
+
+    element('load_basis').addEventListener('click', () => {
+        const choice = element('support').value;
+
+        measure(`basis (${choice})`, BASIS_URL, choices[choice]).catch(error => console.error(error));
+    });
+
+    load_default_environment(scene).then(applied => {
+        if (applied) {
+            renderer.indicate_view_change();
+        }
+    });
+
+    document.body.focus();
+
+    set_status('ready — load one, then the other', 'pass');
+
+    create_frame_loop(time_delta_s => {
+        const width = window.innerWidth;
+        const height = window.innerHeight;
+
+        renderer.resize(width, height);
+        renderer.pixel_ratio = window.devicePixelRatio;
+        camera.aspect = width / height;
+
+        controller.update();
+
+        renderer.render(camera, scene, time_delta_s);
+    }, 60);
+}

package/src/shade/playground/basis_textures/make_basis_gltf.d.mts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=make_basis_gltf.d.mts.map

package/src/shade/playground/basis_textures/make_basis_gltf.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_basis_gltf.d.mts","sourceRoot":"","sources":["../../../../../src/shade/playground/basis_textures/make_basis_gltf.mjs"],"names":[],"mappings":""}

package/src/shade/playground/basis_textures/make_basis_gltf.mjs

@@ -0,0 +1,197 @@
+/**
+ * Re-encode a glTF's textures to KTX2/Basis and rewrite it to use `KHR_texture_basisu`.
+ *
+ * **A dev tool, not engine code.** §8 puts the offline encoder out of scope deliberately — first-
+ * party content is compressed by a tool, and this is that tool at its smallest: enough to turn a
+ * model the repository already has into the thing the transcoder exists to read, so the playground
+ * beside it has something to load.
+ *
+ * It shells out to `basisu`, which is not a dependency of anything here. Install it with
+ * `npm i --no-save basis_universal` in this directory, or put the binary on `PATH`.
+ *
+ * Usage:
+ *
+ *     node make_basis_gltf.mjs <input.gltf> <output-directory> [--uastc|--etc1s|--mixed]
+ *
+ * `--mixed` is the default and the interesting one: **UASTC for normal maps and ETC1S for
+ * everything else**, which is what a real pipeline does. ETC1S puts a block's four colours on a line
+ * through the grey axis, which is a fair model of a photograph and a poor one of a direction, so a
+ * normal map encoded that way bands visibly. The playground's whole point is that the loader then
+ * picks BC5 for those and BC7 for the rest, from the material slot alone.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+const [input, output_directory, mode = "--mixed"] = process.argv.slice(2);
+
+if (input === undefined || output_directory === undefined) {
+    console.error("usage: node make_basis_gltf.mjs <input.gltf> <output-directory> [--mixed|--uastc|--etc1s]");
+    process.exit(2);
+}
+
+/**
+ * Where `basisu` is, preferring a locally installed copy over one on `PATH`.
+ *
+ * @returns {string[]} the command and its leading arguments
+ */
+function basisu_command() {
+    const local = path.resolve(
+        path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, "$1")),
+        "node_modules", "basis_universal", "bin",
+        process.platform === "win32" ? "basisu.exe" : "basisu"
+    );
+
+    return fs.existsSync(local) ? [local] : ["basisu"];
+}
+
+const BASISU = basisu_command();
+
+const source_directory = path.dirname(input);
+
+const gltf = JSON.parse(fs.readFileSync(input, "utf8"));
+
+fs.mkdirSync(output_directory, { recursive: true });
+
+/**
+ * Which material slot each texture fills, so a normal map can be encoded differently.
+ *
+ * The same question `gltf_image_roles` asks of the loaded document, asked here of the file — the
+ * encoder needs it for a different reason (which *encoding* to use) than the loader does (which
+ * *format* to transcode into), and neither can answer the other's.
+ *
+ * @returns {Map<number, string>} image index to slot name
+ */
+function image_slots() {
+    const slots = new Map();
+
+    /**
+     * @param {object|undefined} reference
+     * @param {string} slot
+     */
+    function claim(reference, slot) {
+        if (reference === undefined) {
+            return;
+        }
+
+        const texture = gltf.textures[reference.index];
+
+        if (texture?.source !== undefined) {
+            slots.set(texture.source, slot);
+        }
+    }
+
+    for (const material of gltf.materials ?? []) {
+        claim(material.normalTexture, "normal");
+        claim(material.occlusionTexture, "orm");
+        claim(material.emissiveTexture, "emissive");
+
+        const pbr = material.pbrMetallicRoughness;
+
+        if (pbr !== undefined) {
+            claim(pbr.baseColorTexture, "albedo");
+            claim(pbr.metallicRoughnessTexture, "orm");
+        }
+    }
+
+    return slots;
+}
+
+const slots = image_slots();
+
+let encoded = 0;
+let source_bytes = 0;
+let basis_bytes = 0;
+
+for (let index = 0; index < gltf.images.length; index++) {
+    const image = gltf.images[index];
+
+    if (image.uri === undefined) {
+        throw new Error(`images[${index}] has no uri; only file-backed images are handled`);
+    }
+
+    const source = path.join(source_directory, decodeURIComponent(image.uri));
+
+    const name = `${path.basename(image.uri, path.extname(image.uri))}.ktx2`;
+
+    const destination = path.join(output_directory, name);
+
+    const slot = slots.get(index);
+
+    /*
+     A normal map takes UASTC where the mode allows it; everything else takes ETC1S, which is a
+     quarter the size and what colour is normally shipped as. `-linear` for anything that is not a
+     colour: an ORM map's channels are quantities and its mip chain must not be filtered in sRGB.
+    */
+    const uastc = mode === "--uastc" || (mode === "--mixed" && slot === "normal");
+
+    const linear = slot === "normal" || slot === "orm";
+
+    /*
+     No `-y_flip`. glTF puts UV (0,0) at the top-left of the image, and a KTX2 with no
+     `KTXorientation` key — which is what `basisu` writes either way — means exactly that, so
+     `KHR_texture_basisu` requires the payload to be stored top-down. `-y_flip` bakes a vertical
+     mirror into the pixels and records nothing about it, which no reader can detect or undo.
+
+     It was here, and every texture in the converted model was upside down (§9.13). `-y_flip` is for
+     the OpenGL convention, where UV (0,0) is bottom-left; glTF is not that.
+    */
+    const args = [
+        "-ktx2", "-mipmap",
+        ...(uastc ? ["-uastc", "-uastc_level", "2"] : ["-q", "192"]),
+        ...(linear ? ["-linear"] : []),
+        "-file", source,
+        "-output_file", destination,
+    ];
+
+    execFileSync(BASISU[0], [...BASISU.slice(1), ...args], { stdio: "pipe" });
+
+    source_bytes += fs.statSync(source).size;
+    basis_bytes += fs.statSync(destination).size;
+
+    image.uri = name;
+    image.mimeType = "image/ktx2";
+
+    encoded++;
+
+    if (encoded % 10 === 0) {
+        console.log(`  ${encoded}/${gltf.images.length}`);
+    }
+}
+
+/*
+ Every texture now reaches its image through the extension rather than through `source`. `source` is
+ left in place and pointing at the same image, which is what a real exporter does when it has no
+ fallback to offer — the extension is not listed as required, so a reader that does not know it
+ still finds *an* image, and one that does prefers the KTX2.
+*/
+for (const texture of gltf.textures) {
+    texture.extensions = { ...texture.extensions, KHR_texture_basisu: { source: texture.source } };
+}
+
+gltf.extensionsUsed = [...new Set([...(gltf.extensionsUsed ?? []), "KHR_texture_basisu"])];
+
+// the buffers are unchanged, so they are referenced where they already are rather than copied
+for (const buffer of gltf.buffers ?? []) {
+    if (buffer.uri !== undefined && !/^data:/.test(buffer.uri)) {
+        fs.copyFileSync(
+            path.join(source_directory, decodeURIComponent(buffer.uri)),
+            path.join(output_directory, path.basename(buffer.uri))
+        );
+
+        buffer.uri = path.basename(buffer.uri);
+    }
+}
+
+const out = path.join(output_directory, path.basename(input));
+
+fs.writeFileSync(out, JSON.stringify(gltf));
+
+const mib = bytes => `${(bytes / 1048576).toFixed(1)} MiB`;
+
+console.log(`${encoded} images: ${mib(source_bytes)} source -> ${mib(basis_bytes)} basis`);
+console.log(`wrote ${out}`);

package/src/shade/playground/basis_textures/texture_inventory.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What textures a loaded scene has, what formats they are in, and which slots they came from.
+ *
+ * **Counted over distinct images, not over slots.** Sponza's materials name sixty-nine images
+ * between them and share most of them, so counting once per slot reports a number several times too
+ * large. Deduplicating is what makes "how many textures does this scene have" the same question
+ * {@link TextureManager} answers, so the two can be put in one table.
+ *
+ * **No bytes here.** `TextureManager.gpu_memory_usage` is the measurement this page exists to take,
+ * and a second byte count derived from the texel data would be a prediction of it — one that would
+ * silently disagree the moment a mip chain is generated on the device rather than shipped. This says
+ * *what* is resident; the manager says what it costs.
+ *
+ * @param {Node3D[]} roots
+ * @returns {{count: number, formats: Map<string, {count: number, slots: Set<string>}>, textures: ShadeTexture[]}}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function texture_inventory(roots: Node3D[]): {
+    count: number;
+    formats: Map<string, {
+        count: number;
+        slots: Set<string>;
+    }>;
+    textures: ShadeTexture[];
+};
+//# sourceMappingURL=texture_inventory.d.ts.map

package/src/shade/playground/basis_textures/texture_inventory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture_inventory.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/basis_textures/texture_inventory.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;GAkBG;AACH,yCANW,QAAQ;WACE,MAAM;aAAW,IAAI,MAAM,EAAE;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,IAAI,MAAM,CAAC,CAAA;KAAC,CAAC;cAAY,cAAc;EAgE/G"}

package/src/shade/playground/basis_textures/texture_inventory.js

@@ -0,0 +1,98 @@
+import { texture_format_from_shade_image } from "../../renderer/texture/format/texture_format_from_shade_image.js";
+
+/**
+ * The material slots a texture can arrive in, and the role each stands for.
+ *
+ * Named here rather than derived because the point of the breakdown is to show that the *role*
+ * decided the format — a normal map reaching `bc5-rg-unorm` and nothing else doing so is the whole
+ * claim, and it only reads as evidence if the two columns are put side by side.
+ *
+ * @readonly
+ * @type {[string, string][]}
+ */
+const SLOTS = [
+    ["texture_albedo", "albedo"],
+    ["texture_normal", "normal"],
+    ["texture_orm", "orm"],
+    ["texture_emissive", "emissive"],
+];
+
+/**
+ * What textures a loaded scene has, what formats they are in, and which slots they came from.
+ *
+ * **Counted over distinct images, not over slots.** Sponza's materials name sixty-nine images
+ * between them and share most of them, so counting once per slot reports a number several times too
+ * large. Deduplicating is what makes "how many textures does this scene have" the same question
+ * {@link TextureManager} answers, so the two can be put in one table.
+ *
+ * **No bytes here.** `TextureManager.gpu_memory_usage` is the measurement this page exists to take,
+ * and a second byte count derived from the texel data would be a prediction of it — one that would
+ * silently disagree the moment a mip chain is generated on the device rather than shipped. This says
+ * *what* is resident; the manager says what it costs.
+ *
+ * @param {Node3D[]} roots
+ * @returns {{count: number, formats: Map<string, {count: number, slots: Set<string>}>, textures: ShadeTexture[]}}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function texture_inventory(roots) {
+    const formats = new Map();
+
+    const images = new Set();
+    const textures = new Set();
+
+    for (const root of roots) {
+        root.traverse(node => {
+            const material = node.material;
+
+            if (material === undefined || material === null) {
+                return;
+            }
+
+            for (const [slot, role] of SLOTS) {
+                const texture = material[slot];
+
+                if (texture === undefined || texture === null) {
+                    continue;
+                }
+
+                /*
+                 Two textures can share an image and differ in sampler, so the upload set is keyed on
+                 the texture and the format breakdown on the image. Keying both the same way would
+                 either miss an upload or count a picture twice.
+                */
+                textures.add(texture);
+
+                const image = texture.image;
+
+                if (image === undefined || image === null || images.has(image)) {
+                    continue;
+                }
+
+                images.add(image);
+
+                /*
+                 The format the *texture* will be created in, not the one its payload is stored as.
+
+                 They differ in exactly the place that matters: `bc7-rgba-unorm` and
+                 `bc7-rgba-unorm-srgb` are the same bytes, so a payload can only ever name the
+                 former, while whether sampling decodes sRGB is decided here from the image's
+                 `color_space`. Reporting the payload's name hid an albedo map on a linear format
+                 behind a column that looked right — read the descriptor's answer instead, which is
+                 also what puts the two paths' albedo rows side by side.
+                */
+                const format = texture_format_from_shade_image(image);
+
+                const entry = formats.get(format) ?? { count: 0, slots: new Set() };
+
+                entry.count++;
+                entry.slots.add(role);
+
+                formats.set(format, entry);
+            }
+        });
+    }
+
+    return { count: images.size, formats, textures: [...textures] };
+}