@woosh/meep-engine 3.14.1 → 3.14.3

package/src/shade/device/timing/profile/frame_graph_extract_topology.js

@@ -1,174 +1,164 @@
-import { assert } from "../../../../core/assert.js";
-import { gpu_texture_format_info } from "../../../descriptor/texture/format/gpu_texture_format_info.js";
-import {
-    GPUProfilePass,
-    GPUProfileResource,
-    GPUProfileResourceKind,
-    GPUProfileScope,
-    GPUProfileTopology
-} from "./GPUProfileTopology.js";
-
-/**
- * Declared bytes for a texture descriptor: the whole mip chain, at the given sample count.
- *
- * A format the engine's table does not know reports 0 rather than throwing. A capture is a
- * diagnostic; refusing to record one because a size could not be worked out would be the wrong
- * trade every time.
- *
- * @param {TextureResourceDescriptor} descriptor
- * @returns {number}
- */
-function texture_byte_size(descriptor) {
-    let info;
-
-    try {
-        info = gpu_texture_format_info(descriptor.format);
-    } catch {
-        // `gpu_texture_format_info` throws on a name it does not know. Correct for the renderer,
-        // wrong here: a capture is a diagnostic, and losing the whole recording because one
-        // resource used a format the table has not caught up with is the wrong trade every time.
-        return 0;
-    }
-
-    const { block_width, block_height, bytes_per_block } = info;
-
-    let total = 0;
-
-    for (let mip = 0; mip < descriptor.mipLevelCount; mip++) {
-        const w = Math.max(1, Math.floor(descriptor.resolution[0]) >> mip);
-        const h = Math.max(1, Math.floor(descriptor.resolution[1]) >> mip);
-        const d = Math.max(1, Math.floor(descriptor.resolution[2]) >> mip);
-
-        total += Math.ceil(w / block_width) * Math.ceil(h / block_height) * d * bytes_per_block;
-    }
-
-    return total * descriptor.sampleCount;
-}
-
-/**
- * Record the shape of a compiled frame graph.
- *
- * **Call after `compile`, and ideally after `execute`.** Reference counts and cull decisions are
- * what `compile` derives; before it every pass reads as culled, which would be recorded as a frame
- * in which nothing ran.
- *
- * Resources are keyed by **node**, one per version, matching `FrameGraph.exportToJson`. Passes
- * record the node they touched rather than the underlying resource, so a registry-keyed model would
- * leave every reference past version 0 pointing at nothing.
- *
- * @param {FrameGraph} graph
- * @returns {GPUProfileTopology}
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export function frame_graph_extract_topology(graph) {
-    assert.defined(graph, 'graph');
-
-    const topology = new GPUProfileTopology();
-
-    topology.name = graph.name;
-
-    /**
-     * Scopes are reached through the nodes that were recorded inside them, and flattened to an
-     * array here. `FrameGraph` keeps them as a parent chain rather than a list, so this walk is
-     * what turns the chain into something a reader can index.
-     *
-     * @type {Map<FrameGraphScope, number>}
-     */
-    const scope_ids = new Map();
-
-    /**
-     * @param {FrameGraphScope|null} scope
-     * @returns {number} index, or -1
-     */
-    function intern_scope(scope) {
-        if (scope === null || scope === undefined) {
-            return -1;
-        }
-
-        const existing = scope_ids.get(scope);
-
-        if (existing !== undefined) {
-            return existing;
-        }
-
-        // parent first, so a parent always has a lower index than its children and a reader can
-        // resolve the chain in one forward pass
-        const parent = intern_scope(scope.parent);
-
-        const record = new GPUProfileScope();
-
-        record.name = scope.name;
-        record.parent = parent;
-
-        const id = topology.scopes.length;
-
-        topology.scopes.push(record);
-        scope_ids.set(scope, id);
-
-        return id;
-    }
-
-    for (const node of graph.__pass_nodes) {
-        const pass = new GPUProfilePass();
-
-        pass.id = node.id;
-        pass.name = node.name;
-        pass.scope = intern_scope(node.scope);
-        pass.culled = !node.can_execute();
-        pass.has_side_effects = node.has_side_effects;
-        pass.ref_count = node.ref_count;
-        pass.reads = node.resource_reads.slice();
-        pass.writes = node.resource_writes.slice();
-        pass.creates = node.resource_creates.slice();
-
-        topology.passes.push(pass);
-    }
-
-    for (const node of graph.__resource_nodes) {
-        const entry = graph.__resource_registry[node.resource_id];
-
-        const resource = new GPUProfileResource();
-
-        resource.id = node.id;
-        resource.name = node.name;
-        resource.version = node.version;
-        resource.producer = node.producer !== null ? node.producer.id : -1;
-
-        if (entry !== undefined) {
-            resource.transient = entry.isTransient();
-            resource.imported = entry.isImported();
-        }
-
-        const descriptor = entry?.resource_descriptor;
-
-        if (descriptor !== undefined && descriptor !== null) {
-            const type = descriptor.type;
-
-            if (type === 'buffer') {
-                resource.kind = GPUProfileResourceKind.BUFFER;
-                resource.size = descriptor.size;
-                resource.usage = descriptor.usage;
-                resource.byte_size = descriptor.size;
-            } else if (type === 'texture') {
-                resource.kind = GPUProfileResourceKind.TEXTURE;
-                resource.resolution = [
-                    Math.floor(descriptor.resolution[0]),
-                    Math.floor(descriptor.resolution[1]),
-                    Math.floor(descriptor.resolution[2])
-                ];
-                resource.mip_level_count = descriptor.mipLevelCount;
-                resource.sample_count = descriptor.sampleCount;
-                resource.format = descriptor.format;
-                resource.dimension = descriptor.dimension;
-                resource.usage = descriptor.usage;
-                resource.byte_size = texture_byte_size(descriptor);
-            }
-        }
-
-        topology.resources.push(resource);
-    }
-
-    return topology;
-}
+import { assert } from "../../../../core/assert.js";
+import { gpu_texture_format_memory_footprint } from "../../../descriptor/texture/format/gpu_texture_format_info.js";
+import {
+    GPUProfilePass,
+    GPUProfileResource,
+    GPUProfileResourceKind,
+    GPUProfileScope,
+    GPUProfileTopology
+} from "./GPUProfileTopology.js";
+
+/**
+ * Declared bytes for a texture descriptor: the whole mip chain, at the given sample count.
+ *
+ * A format the engine's table does not know reports 0 rather than throwing. A capture is a
+ * diagnostic; refusing to record one because a size could not be worked out would be the wrong
+ * trade every time.
+ *
+ * @param {TextureResourceDescriptor} descriptor
+ * @returns {number}
+ */
+function texture_byte_size(descriptor) {
+    try {
+        return gpu_texture_format_memory_footprint(
+            descriptor.format,
+            descriptor.resolution,
+            descriptor.dimension,
+            descriptor.mipLevelCount,
+            descriptor.sampleCount
+        );
+    } catch {
+        // `gpu_texture_format_info` throws on a name it does not know. Correct for the renderer,
+        // wrong here: a capture is a diagnostic, and losing the whole recording because one
+        // resource used a format the table has not caught up with is the wrong trade every time.
+        return 0;
+    }
+}
+
+/**
+ * Record the shape of a compiled frame graph.
+ *
+ * **Call after `compile`, and ideally after `execute`.** Reference counts and cull decisions are
+ * what `compile` derives; before it every pass reads as culled, which would be recorded as a frame
+ * in which nothing ran.
+ *
+ * Resources are keyed by **node**, one per version, matching `FrameGraph.exportToJson`. Passes
+ * record the node they touched rather than the underlying resource, so a registry-keyed model would
+ * leave every reference past version 0 pointing at nothing.
+ *
+ * @param {FrameGraph} graph
+ * @returns {GPUProfileTopology}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function frame_graph_extract_topology(graph) {
+    assert.defined(graph, 'graph');
+
+    const topology = new GPUProfileTopology();
+
+    topology.name = graph.name;
+
+    /**
+     * Scopes are reached through the nodes that were recorded inside them, and flattened to an
+     * array here. `FrameGraph` keeps them as a parent chain rather than a list, so this walk is
+     * what turns the chain into something a reader can index.
+     *
+     * @type {Map<FrameGraphScope, number>}
+     */
+    const scope_ids = new Map();
+
+    /**
+     * @param {FrameGraphScope|null} scope
+     * @returns {number} index, or -1
+     */
+    function intern_scope(scope) {
+        if (scope === null || scope === undefined) {
+            return -1;
+        }
+
+        const existing = scope_ids.get(scope);
+
+        if (existing !== undefined) {
+            return existing;
+        }
+
+        // parent first, so a parent always has a lower index than its children and a reader can
+        // resolve the chain in one forward pass
+        const parent = intern_scope(scope.parent);
+
+        const record = new GPUProfileScope();
+
+        record.name = scope.name;
+        record.parent = parent;
+
+        const id = topology.scopes.length;
+
+        topology.scopes.push(record);
+        scope_ids.set(scope, id);
+
+        return id;
+    }
+
+    for (const node of graph.__pass_nodes) {
+        const pass = new GPUProfilePass();
+
+        pass.id = node.id;
+        pass.name = node.name;
+        pass.scope = intern_scope(node.scope);
+        pass.culled = !node.can_execute();
+        pass.has_side_effects = node.has_side_effects;
+        pass.ref_count = node.ref_count;
+        pass.reads = node.resource_reads.slice();
+        pass.writes = node.resource_writes.slice();
+        pass.creates = node.resource_creates.slice();
+
+        topology.passes.push(pass);
+    }
+
+    for (const node of graph.__resource_nodes) {
+        const entry = graph.__resource_registry[node.resource_id];
+
+        const resource = new GPUProfileResource();
+
+        resource.id = node.id;
+        resource.name = node.name;
+        resource.version = node.version;
+        resource.producer = node.producer !== null ? node.producer.id : -1;
+
+        if (entry !== undefined) {
+            resource.transient = entry.isTransient();
+            resource.imported = entry.isImported();
+        }
+
+        const descriptor = entry?.resource_descriptor;
+
+        if (descriptor !== undefined && descriptor !== null) {
+            const type = descriptor.type;
+
+            if (type === 'buffer') {
+                resource.kind = GPUProfileResourceKind.BUFFER;
+                resource.size = descriptor.size;
+                resource.usage = descriptor.usage;
+                resource.byte_size = descriptor.size;
+            } else if (type === 'texture') {
+                resource.kind = GPUProfileResourceKind.TEXTURE;
+                resource.resolution = [
+                    Math.floor(descriptor.resolution[0]),
+                    Math.floor(descriptor.resolution[1]),
+                    Math.floor(descriptor.resolution[2])
+                ];
+                resource.mip_level_count = descriptor.mipLevelCount;
+                resource.sample_count = descriptor.sampleCount;
+                resource.format = descriptor.format;
+                resource.dimension = descriptor.dimension;
+                resource.usage = descriptor.usage;
+                resource.byte_size = texture_byte_size(descriptor);
+            }
+        }
+
+        topology.resources.push(resource);
+    }
+
+    return topology;
+}

package/src/shade/playground/basis_textures/README.md

@@ -0,0 +1,105 @@
+# Basis / KTX2 textures
+
+The same scene twice — once with JPEG textures the browser decodes to RGBA8, once with KTX2/Basis
+textures the engine transcodes to a block format — with the GPU memory each costs.
+
+This is tier 8 of the compressed-texture plan's testing ladder, and the only tier with a GPU in it.
+Everything below it runs device-free: the transcoders against the reference encoder's own output,
+the container reader against real and synthesised files, the format tables against themselves. What
+none of that can answer is whether a transcoded payload is a *texture* — whether `createTexture`
+accepts the format, and whether `writeTexture` accepts the block-aligned row layout that a
+container's mip chain implies.
+
+## Running it
+
+```bash
+npm run dev --workspace @woosh/meep-engine
+```
+
+Then open `/src/shade/playground/basis_textures/index.html`.
+
+Both models are served out of `test_assets/`, which is gitignored — see `test_assets/README.md` for
+how to put Sponza there. The Basis variant is built from it by the tool beside this file:
+
+```bash
+node make_basis_gltf.mjs ../../../../test_assets/Sponza/glTF/Sponza.gltf ../../../../test_assets/Sponza_basis
+```
+
+That needs the `basisu` encoder, which is not a dependency of anything here — `npm i --no-save
+basis_universal` in this directory, or put the binary on `PATH`. It encodes normal maps as UASTC and
+everything else as ETC1S, which is what a real pipeline does and what makes the two transcoder paths
+both appear in one scene.
+
+## What it measured
+
+On an NVIDIA Lovelace device, 2026-09-02:
+
+| | textures | GPU memory | formats |
+|---|---|---|---|
+| JPEG | 69 | 335.3 MiB | 69 × `rgba8` |
+| Basis | 69 | 83.8 MiB | 45 × `bc7-rgba-unorm`, 24 × `bc5-rg-unorm` |
+
+**4.00× less texture memory**, both sides counted the same way and both including their full mip
+chain. All 69 textures uploaded; none was refused by the device.
+
+The format split is the role wiring working: the 24 normal maps are the 24 BC5 textures, chosen
+because a tangent-space normal reconstructs Z in the shader and so spends its eight bits per texel
+on two channels instead of four. Nothing else in the scene reaches BC5.
+
+Three things this page found that no device-free test had:
+
+- **Mip generation was requested for block formats.** `ShadeTexture` asks for generated mips by
+  default, which is right for a decoded JPEG and impossible for a transcoded payload — no BC format
+  can be a render attachment. Every compressed texture was refused at upload. Fixed in `load_gltf`,
+  which now clears the flag when the image's format cannot generate them; the chain in the container
+  is used instead.
+- **`TextureManager.gpu_memory_usage` is a running total, and nothing evicts.** Taking a scene out of
+  the graph leaves its textures in the cache, so reading the total after the second load reported the
+  sum of both and flattered the comparison to 5.00×. The page measures the difference across the
+  upload instead.
+- **Every texture was upside down**, which no number on this page could see — the VRAM table was
+  correct in every particular while the scene was mirrored. `make_basis_gltf.mjs` passed `-y_flip` to
+  `basisu`. glTF puts UV (0,0) at the top-left, and a KTX2 with no `KTXorientation` key means exactly
+  that, so `KHR_texture_basisu` wants a top-down payload; `basisu` writes no such key either way, so
+  the flag bakes in a mirror that no reader can detect or undo. The engine was never at fault. Verify
+  a converter change by encoding an image with a top/bottom asymmetry and checking which row comes
+  back — that is how this was pinned.
+
+## The uncompressed floor
+
+Set **pretend support** to `none` and the scene still loads, at 335.3 MiB across the same 69
+textures — exactly what the JPEG path costs, and with the same sRGB split. Every compressed format in
+WebGPU is an optional feature, so a device exposing none of them is legal; `rgba8unorm` is mandatory,
+so it is the floor. It is also the fastest path here (11.4 s against ~19 s), because the BC re-encode
+is the expensive half and this skips it.
+
+## Known gap
+
+**ETC2 is written** — an ETC1S block already *is* an ETC1 block, so it is a repack that matches the
+reference transcoder byte for byte, and an ETC2-capable device gets eight bits a texel instead of
+thirty-two.
+
+**ASTC is written too**, and leads every role's preference on a device that has it. It was pulled
+once — §9.16 — on a misread measurement: the deviation blamed on this decoder was the reference
+encoder's own loss against the ETC1S source. With the specification in hand it came back at **48.81
+dB against `basisu`'s 48.28** on the same fixture, better on total error and one level behind at the
+peak. §9.17 has the arithmetic that mattered: the interpolation widens endpoints to sixteen bits
+before weighting them, and colour endpoint mode 8 swaps and blue-contracts a pair written the wrong
+way round.
+
+**UASTC repacks to ASTC**, which is the path that format was designed for: its fields are ASTC’s
+fields, so nothing is fitted and nothing is lost. Byte-identical to the reference transcoder on 2320
+of 2352 fixture blocks, and provably equivalent on the rest. That closes the last gap — a no-BC
+device now costs **83.8 MiB on Sponza, the same as desktop**, where it was 173.1 MiB.
+
+Still unwritten: ETC2 from UASTC, for a device with ETC2 but not ASTC. The availability figures
+suggest that population is close to empty.
+
+## Why it cannot draw here
+
+The renderer needs `maxImmediateSize` ≥ 24 bytes and assumes the 64-byte floor every conformant
+device reports. A Chrome build without immediate-data support offers 0, and the frame loop then dies
+in `GPUTypedTable/Upload elements` — for every playground in this directory, not just this one. The
+measurements above do not depend on a frame: textures are uploaded explicitly through
+`TextureManager.obtain`, which is the same call the renderer makes and the same moment the device
+accepts the format or does not. Seeing the scene needs a browser with immediate data.

package/src/shade/playground/basis_textures/index.html

@@ -0,0 +1,141 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — Basis / KTX2 textures</title>
+    <style>
+        :root {
+            color-scheme: dark;
+            --panel: rgba(20, 22, 26, 0.88);
+            --line: #2b3038;
+            --text: #d6dae0;
+            --muted: #8b939f;
+            --pass: #55c46a;
+            --fail: #ff6b6b;
+            --warn: #e5b54a;
+        }
+
+        * { box-sizing: border-box; }
+
+        html, body { margin: 0; height: 100%; overflow: hidden; background: #0d0f12; }
+
+        /* body carries tabindex so the camera controller's keyboard device has something focusable
+           to listen on; the focus ring around the whole viewport is not wanted */
+        body:focus { outline: none; }
+
+        #view { display: block; width: 100vw; height: 100vh; }
+
+        #panel {
+            position: fixed;
+            top: 12px;
+            left: 12px;
+            width: 340px;
+            padding: 12px 14px;
+            background: var(--panel);
+            border: 1px solid var(--line);
+            border-radius: 8px;
+            backdrop-filter: blur(6px);
+            color: var(--text);
+            font: 13px/1.5 system-ui, -apple-system, Segoe UI, sans-serif;
+        }
+
+        #panel h1 { font-size: 13px; font-weight: 600; margin: 0 0 8px; }
+
+        hr { border: 0; border-top: 1px solid var(--line); margin: 10px 0; }
+
+        button, select {
+            font: inherit;
+            padding: 5px 11px;
+            border-radius: 6px;
+            border: 1px solid var(--line);
+            background: #1c1f25;
+            color: var(--text);
+            cursor: pointer;
+        }
+
+        button:hover, select:hover { border-color: #3d4552; }
+
+        .row { display: flex; gap: 6px; align-items: center; }
+        .row > * { flex: 0 0 auto; }
+        .row select { flex: 1 1 auto; min-width: 0; }
+
+        #device { font-size: 11.5px; color: var(--muted); margin-bottom: 8px; }
+
+        #status { font-size: 12px; color: var(--muted); word-break: break-word; }
+        #status.pass { color: var(--pass); }
+        #status.fail { color: var(--fail); }
+        #status.warn { color: var(--warn); }
+
+        #report {
+            margin: 8px 0 0;
+            max-height: 46vh;
+            overflow: auto;
+            white-space: pre;
+            font: 11.5px/1.45 ui-monospace, SFMono-Regular, Consolas, monospace;
+            color: var(--text);
+        }
+
+        p.note { margin: 8px 0 0; font-size: 11.5px; color: var(--muted); }
+    </style>
+</head>
+<body tabindex="0">
+
+<canvas id="view"></canvas>
+
+<div id="panel">
+    <h1>Basis / KTX2 textures</h1>
+
+    <div id="device">…</div>
+
+    <div class="row">
+        <button id="load_jpeg">Load JPEG</button>
+        <button id="load_basis">Load Basis</button>
+    </div>
+
+    <p class="note">
+        Load one, then the other. Both are the same model; only the textures differ.
+    </p>
+
+    <hr>
+
+    <div class="row">
+        <span>Pretend support:</span>
+        <select id="support">
+            <option value="device">device</option>
+            <option value="bc7_only">bc7 only</option>
+            <option value="bc1_only">bc1 only</option>
+            <option value="none">none</option>
+        </select>
+    </div>
+
+    <p class="note">
+        Narrowing what the device claims is how the role-to-format choice becomes visible: normal
+        maps take BC5 where it exists and fall back to BC7 where it does not.
+        <strong>none</strong> is the floor — every compressed format is an optional WebGPU feature,
+        so the scene must still load, and does, as rgba8 at four bytes a texel. An ETC2 device gets
+        ETC2 instead, which for ETC1S is a repack rather than a re-encode, and an ASTC one gets ASTC.
+    </p>
+
+    <hr>
+
+    <div id="status"></div>
+    <pre id="report"></pre>
+
+    <p class="note">Drag to orbit, wheel to zoom.</p>
+</div>
+
+<script type="module">
+    import { start } from './main.js';
+
+    start().catch(error => {
+        const status = document.getElementById('status');
+
+        status.className = 'fail';
+        status.textContent = String(error?.message ?? error);
+
+        console.error(error);
+    });
+</script>
+
+</body>
+</html>

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

@@ -0,0 +1,8 @@
+/**
+ * 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 function start(): Promise<void>;
+//# sourceMappingURL=main.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/basis_textures/main.js"],"names":[],"mappings":"AA4FA;;;;;GAKG;AACH,yBAFa,QAAQ,IAAI,CAAC,CA8PzB"}