npm - @woosh/meep-engine - Versions diffs - 3.14.2 → 3.14.3 - Mend

@woosh/meep-engine 3.14.2 → 3.14.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1178) hide show

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

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

	@@ -0,0 +1 @@
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"}

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

@@ -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 ADDED Viewed

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

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

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