@woosh/meep-engine 3.11.3 → 3.13.0

package/src/engine/graphics3/GraphicsEngine3.js

@@ -1,790 +1,10 @@
-import { assert } from "../../core/assert.js";
-import Signal from "../../core/events/signal/Signal.js";
-import Vector1 from "../../core/geom/Vector1.js";
-import { Vector2 } from "../../core/geom/Vector2.js";
-import { max2 } from "../../core/math/max2.js";
-import { TextureDescriptor } from "../../shade/descriptor/texture/TextureDescriptor.js";
-import { PerspectiveCamera } from "../../shade/renderer/camera/PerspectiveCamera.js";
-import { DynamicResolutionScaling } from "../../shade/renderer/DynamicResolutionScaling.js";
-import { Renderer } from "../../shade/renderer/Renderer.js";
-import { Scene } from "../../shade/renderer/scene/Scene.js";
-import { Sampler2D } from "../graphics/texture/sampler/Sampler2D.js";
-import EmptyView from "../../view/elements/EmptyView.js";
-import { make_default_environment } from "./make_default_environment.js";
-import { shade_camera_projection_ray } from "./shade_camera_projection_ray.js";
-import { ShadeCameraAdapter } from "./ShadeCameraAdapter.js";
+import { GraphicsEngine } from "./GraphicsEngine.js";
 
 /**
- * What an offscreen picture is drawn into. Not the canvas's presentation format on purpose: a
- * caller reading pixels back wants a channel order it can name, and the presentation format is
- * whatever the platform prefers.
+ * @deprecated Renamed to {@link GraphicsEngine}. The trailing `3` marked the 2.x → 3.x renderer transition;
+ * the 2.x name it disambiguated against is gone, so the suffix no longer distinguishes anything.
  *
- * @type {string}
+ * Kept as a re-export rather than removed: this is a library, and an import path is as much a
+ * published interface as a class name.
  */
-const OFFSCREEN_FORMAT = "rgba8unorm";
-
-/**
- * Frames an offscreen picture is drawn before it is read.
- *
- * More than one because the frame is temporal: anti-aliasing, and every effect that reads last
- * frame's depth, need a history to have been written before what they produce is the picture rather
- * than the first draft of it. Small because the history is dropped by the resize that precedes it,
- * so this is how long convergence takes from nothing rather than how long it takes to forget a
- * previous subject.
- *
- * @type {number}
- */
-const OFFSCREEN_FRAMES = 8;
-
-/**
- * The frame rate dynamic resolution scaling holds, in frames per second.
- *
- * Thirty, by the sponsor's decision (D39). It is a **floor**, not a target the game aims to sit at:
- * the controller is silent while frames are cheaper than 33 ms, and everything it does happens on
- * hardware that cannot hold that. Raising it would mean trading resolution away on machines that
- * were coping.
- *
- * @type {number}
- */
-const TARGET_FRAME_RATE = 30;
-
-/**
- * The renderer meep 3 talks to: Shade behind the shape `GraphicsEngine` presented.
- *
- * It implements the **bootstrap seam** and nothing else — `{viewport, domElement, camera,
- * on.{preRender, postRender, contextLost, contextRestored, contextFailed}, needDraw, autoDraw,
- * start(), stop(), render(), updateSize()}` — because that is what `Engine` needs in order to boot,
- * and because the facade is deliberately not allowed to grow past §4.2 (D14).
- *
- * **Three things have been let through since, each by name.** {@link add_extension} /
- * {@link remove_extension} (E9), because an extension has to survive the restart that replaces the
- * renderer holding it, and
- * {@link scene_context} (E13, D29), because the managers a system needs — animation above all —
- * hang off Shade's per-scene GPU state and there is no other door to them. Both take or return
- * something the caller already owns; neither hands out the renderer.
- *
- * {@link renderer} is the third, and much the widest: it hands the renderer straight out, so
- * everything the other two are shaped to avoid is reachable through it. It is an escape hatch for
- * callers that have no other route, not a migration target — the old engine's 44
- * `.renderer`/`getRenderer()` call sites are each still a migration item.
- *
- * What is deliberately absent, and stays absent: `getRenderer()` (the old engine's accessor, and
- * the shape those call sites are being ported off), `layers` (CPU visibility dies with GPU
- * culling), `scene` (entities reach the scene through the mesh system, not through the facade),
- * and the three-shaped material manager.
- *
- * **Lifecycle differs from the old engine on purpose.** `GraphicsEngine` starts inside the `Engine`
- * constructor, which is why stopping an engine used to leave a restarted one with no renderer at
- * all. This one starts from `Engine.start()` and stops symmetrically, so `start → stop → start`
- * returns a working renderer (E1).
- */
-export class GraphicsEngine3 {
-    /**
-     * Duck-type the rest of the engine checks instead of `instanceof`, which is the convention
-     * the legacy `CameraSystem` already used and `HeadsUpDisplaySystem` was moved onto in Phase 0.
-     *
-     * @returns {boolean}
-     */
-    get isGraphicsEngine() {
-        return true;
-    }
-
-    /**
-     * Shade's renderer. `null` before a successful {@link start} and again after {@link stop} —
-     * the states a caller has to tolerate, which is why {@link render} checks rather than assumes.
-     *
-     * @type {Renderer|null}
-     */
-    #renderer = null;
-
-    /**
-     * Danger zone.
-     * Be careful with what you do, with great Renderer comes great responsibility.
-     * @returns {Renderer|null}
-     */
-    get renderer(){
-        return this.#renderer;
-    }
-
-    /**
-     * Trades internal resolution for frame time — see {@link dynamic_resolution}.
-     *
-     * @type {DynamicResolutionScaling}
-     */
-    #dynamic_resolution = new DynamicResolutionScaling();
-
-    /**
-     * When the previous frame was drawn, in the clock {@link performance} keeps. Seeded by
-     * {@link start} so that the first frame after one has a real interval behind it rather than a
-     * special case.
-     *
-     * @type {number}
-     */
-    #last_render_timestamp = 0;
-
-    /**
-     * Extensions registered through {@link add_extension}, in the order they were added — which is
-     * not the order they record in: that is resolved from their own declarations, per phase, by the
-     * registry the renderer holds.
-     *
-     * The engine holds them rather than the renderer because a renderer is replaced by every
-     * restart while the systems that registered are not, and because a system has to be able to
-     * register before a device exists.
-     *
-     * @type {RenderExtension[]}
-     */
-    #extensions = [];
-
-    /**
-     * The scene Shade draws.
-     *
-     * There is no getter, deliberately. The old engine handed its scene out and the editor wrote
-     * into the graph directly — 14 call sites of coupling that §2.1 retires. Content reaches the
-     * renderer through the system that owns it, which tells the facade *which* scene to draw and
-     * keeps the graph to itself.
-     *
-     * @type {Scene}
-     */
-    #scene = new Scene();
-
-    /**
-     * @type {HTMLCanvasElement|null}
-     */
-    #canvas = null;
-
-    /**
-     * The camera the frame is drawn from. Owned here rather than handed in, because it is Shade's
-     * and a caller building one would have to know that; what drives it is
-     * {@link camera_sync_from_transform}, from whatever transform the active camera entity has.
-     *
-     * @type {PerspectiveCamera}
-     */
-    #camera = new PerspectiveCamera();
-
-    constructor() {
-        /**
-         * The camera, in the shape the engine's existing consumers read it — `projectionMatrix` and
-         * `matrixWorldInverse`, which is what `HeadsUpDisplaySystem` multiplies together. The real
-         * Shade camera is on its `camera` property.
-         *
-         * @type {ShadeCameraAdapter}
-         */
-        this.camera = new ShadeCameraAdapter(this.#camera);
-
-        this.on = {
-            /**
-             * **The camera-finalized phase.** Camera matrices are final and the frame has not been
-             * submitted — which is what §2.1 already defines `preRender` to mean, so the old
-             * engine's `visibilityConstructionStarted` / `visibilityConstructionEnded` do not
-             * survive as signals of their own. Their subscribers — the legacy camera and light
-             * systems, the editor's symbolic display — landed here when their systems were ported.
-             *
-             * @type {Signal}
-             */
-            preRender: new Signal(),
-
-            /**
-             * The frame has been submitted. Note that submitted is not finished — the GPU is still
-             * working when this fires, on this renderer as on the last one.
-             *
-             * @type {Signal}
-             */
-            postRender: new Signal(),
-
-            /**
-             * The GPU device was lost. Nothing renders after this.
-             *
-             * @type {Signal}
-             */
-            contextLost: new Signal(),
-
-            /**
-             * **Never fires.** Kept because the contract has it and subscribers expect the shape,
-             * but Shade does not recover a lost device (R6): everything the renderer built lived on
-             * it, and a message plus a reload is the honest response. A subscriber here is waiting
-             * for something that will not happen.
-             *
-             * @type {Signal<number>}
-             */
-            contextRestored: new Signal(),
-
-            /**
-             * There will be no rendering — no WebGPU, no adapter, or hardware below the floor.
-             * Carries a {@link ShadeDeviceFailure}, whose `message` is written to be shown.
-             *
-             * @type {Signal<ShadeDeviceFailure>}
-             */
-            contextFailed: new Signal(),
-        };
-
-        /**
-         * @type {Vector1}
-         */
-        this.pixelRatio = new Vector1(1);
-
-        /**
-         * Final render resolution in whole device pixels. Zero until the viewport has a size.
-         *
-         * @readonly
-         * @type {Vector2}
-         */
-        this.output_resolution = new Vector2(0, 0);
-
-        /**
-         * The DOM element the canvas lives in. Created here rather than in {@link start} so that
-         * layout can be wired before a device exists — and so a failed start still leaves something
-         * to put a message in.
-         *
-         * @type {EmptyView}
-         */
-        this.viewport = new EmptyView();
-        this.viewport.size.onChanged.add(this.updateSize, this);
-
-        /**
-         * @type {HTMLCanvasElement|null}
-         */
-        this.domElement = null;
-
-        /**
-         * Whether the next frame has anything new to show. With {@link autoDraw} off, this is what
-         * gates rendering at all.
-         *
-         * @type {boolean}
-         */
-        this.needDraw = true;
-
-        /**
-         * Draw every tick regardless of {@link needDraw}. On-demand rendering — menus and the
-         * editor that should not burn frames — is turning this off.
-         *
-         * @type {boolean}
-         */
-        this.autoDraw = true;
-
-        /**
-         * @type {number}
-         */
-        this.frameIndex = 0;
-
-        /*
-         Wired here rather than in `start`, because the closures read the field and the field is
-         re-assigned on every start: a controller that captured one renderer would keep steering it
-         after a context restart replaced it.
-        */
-        this.#dynamic_resolution.get_scale = () => this.#renderer.internal_resolution_scale;
-        this.#dynamic_resolution.set_scale = v => {
-            this.#renderer.internal_resolution_scale = v;
-        };
-
-        /*
-         Stated rather than inherited. It happens to equal the controller's own default today, and
-         that is not a reason to leave it unsaid: the game's target is the game's decision (D39), and
-         a library default is free to move without anybody meaning the game to follow it.
-        */
-        this.#dynamic_resolution.target_frame_rate = TARGET_FRAME_RATE;
-    }
-
-    /**
-     * Trades internal resolution for frame time, and is the only thing in this engine that does.
-     *
-     * Exposed so that it can be turned off or re-targeted — a measurement that wants a fixed
-     * resolution, or a settings screen that offers the choice — and for no other reason: it drives
-     * itself from {@link render}, and nothing has to call it.
-     *
-     * **It targets {@link TARGET_FRAME_RATE}**, which makes it a floor-holder rather than a
-     * frame-rate governor: it does nothing at all until a frame costs more than 33 ms, and on
-     * hardware that clears the budget it sits at full resolution and never engages.
-     *
-     * @returns {DynamicResolutionScaling}
-     */
-    get dynamic_resolution() {
-        return this.#dynamic_resolution;
-    }
-
-    /**
-     * Draw this scene from now on.
-     *
-     * The narrowest seam that works: the facade is told what to draw, rather than handing out a
-     * graph for anyone to write into. Shade's own `render` takes the scene as an argument, so this
-     * matches how the renderer underneath already thinks about it.
-     *
-     * @param {Scene} scene
-     */
-    set_scene(scene) {
-        assert.defined(scene, 'scene');
-        assert.equal(scene.isScene, true, 'scene.isScene !== true');
-
-        this.#scene = scene;
-
-        /*
-         Shade lights with indirect by default and a scene without an environment renders unlit, so
-         the engine supplies one rather than leaving every caller to. Turning global illumination off
-         is the thing that takes a decision, not turning it on.
-
-         A scene that arrives with an environment keeps it: the scene owns its lighting and this only
-         fills in what is missing. Otherwise handing over a scene would silently discard the
-         environment it was built with, and the fix would be to call things in a particular order.
-         */
-        if (scene.lights.environment === undefined) {
-            scene.lights.environment = make_default_environment();
-        }
-    }
-
-    /**
-     * Set the scene's image-based-lighting source, replacing whatever it was lighting with.
-     *
-     * No prefiltering happens here, unlike the equivalent on the old engine: Shade convolves the map
-     * into its irradiance and roughness mips on the GPU, notices when the texture it was given has
-     * been swapped, and redoes that work itself. So this is an assignment and the renderer catches up
-     * on the next frame — safe before startup as well as after.
-     *
-     * The texture must be **octahedral**, which is the projection Shade samples the environment with.
-     * `load_environment_map` and `resample_equirectangular_to_octahedral` are the ways in; a cube or
-     * equirectangular texture handed over directly would sample as garbage rather than fail.
-     *
-     * There is deliberately no `set_environment_texture` counterpart. On the old engine that meant
-     * "and show it as the skybox too", and Shade has no background of its own to show it on — the
-     * visible sky is its own piece of work rather than a second line here.
-     *
-     * @param {ShadeTexture} texture octahedral-encoded spherical radiance
-     */
-    set_environment_map(texture) {
-        assert.defined(texture, 'texture');
-        assert.equal(texture.isShadeTexture, true, 'texture.isShadeTexture !== true');
-
-        this.#scene.lights.environment = texture;
-
-        this.needDraw = true;
-    }
-
-    /**
-     * Record work into the frame at a named point in it — §4.8's extensibility surface, and the
-     * honest replacement for the old engine's `preRender` / `buffersRendered` / `postRender`
-     * signals, each of which maps to a phase.
-     *
-     * The extension is handed a `FrameContext` when its phase comes round and records with the
-     * `graph_*` helpers, exactly as the built-in passes do. Resource handles come from the frame's
-     * records rather than from a renderer: the frame graph is what knows which resources a pass
-     * touched, and work recorded around it cannot be ordered or aliased against the rest of the
-     * frame.
-     *
-     * **Registering does not require a device.** Extensions are held here and applied to the
-     * renderer when one exists, and again after a restart — a system registers at startup without
-     * knowing where in the lifecycle it is.
-     *
-     * @param {RenderExtension} extension
-     * @returns {RenderExtension} `extension`, for handing back to {@link remove_extension}
-     */
-    add_extension(extension) {
-        assert.defined(extension, 'extension');
-        assert.isFunction(extension.record, 'extension.record');
-
-        this.#extensions.push(extension);
-
-        if (this.#renderer !== null) {
-            this.#renderer.add_extension(extension);
-        }
-
-        return extension;
-    }
-
-    /**
-     * How many extensions are registered against a phase.
-     *
-     * Read-only, and here because a system that registers one otherwise has no way to say that it
-     * did: the extension is private to the system that owns it, and "start → stop → start leaks
-     * nothing" is a property a gate has to be able to state. It says how many, not what they are,
-     * and hands out nothing.
-     *
-     * @param {FramePhase} phase
-     * @returns {number}
-     */
-    extension_count(phase) {
-        assert.isNonNegativeInteger(phase, 'phase');
-
-        let count = 0;
-
-        for (let i = 0; i < this.#extensions.length; i++) {
-            if (this.#extensions[i].phase === phase) {
-                count++;
-            }
-        }
-
-        return count;
-    }
-
-    /**
-     * Take an extension back out. Identity is the object, so the phase does not have to be
-     * repeated.
-     *
-     * @param {RenderExtension} extension
-     * @returns {boolean} whether it was registered
-     */
-    remove_extension(extension) {
-        const index = this.#extensions.indexOf(extension);
-
-        if (index === -1) {
-            return false;
-        }
-
-        this.#extensions.splice(index, 1);
-
-        if (this.#renderer !== null) {
-            this.#renderer.remove_extension(extension);
-        }
-
-        return true;
-    }
-
-    /**
-     * Shade's GPU-side state for a scene the caller already owns — and with it the managers that
-     * hang off it, of which the animation manager is the one Phase 4 needs.
-     *
-     * **The one thing D14 lets through, and D29 is why** (E13). The alternative was a system
-     * registering a frame pass that draws nothing, purely to be handed `context.view.scene` when
-     * its phase came round — which would have made the animation system claim a moment in drawing
-     * for work that is not drawing. A named method costs one line of surface and says what it is.
-     *
-     * **This still hands out no graph.** `scene` is an argument, not a getter: only the system that
-     * owns a scene can ask about it, so the coupling §2.1 retires — the facade handing its graph to
-     * anyone who asks — is not what this is. What comes back is the renderer's own bookkeeping for
-     * that scene, which is Shade's to shape and no one else's.
-     *
-     * @param {Scene} scene
-     * @returns {GPUSceneContext|null} `null` while there is no device — before a successful
-     * {@link start} and again after {@link stop}. A restart builds a **new** context, so a caller
-     * holding ids the old one issued has to notice the object changed and register again.
-     */
-    scene_context(scene) {
-        assert.defined(scene, 'scene');
-        assert.equal(scene.isScene, true, 'scene.isScene !== true');
-
-        const renderer = this.#renderer;
-
-        if (renderer === null) {
-            return null;
-        }
-
-        return renderer.scenes.obtain(scene);
-    }
-
-    /**
-     * Draw a scene of somebody else's into a texture of that size, and hand back its pixels.
-     *
-     * **Tooling only.** This is a GPU readback and I-4 forbids those on any gameplay-affecting path;
-     * what it is here for is pictures of things — an asset library's icons, a thumbnail, a capture.
-     *
-     * **No renderer and no device leave the facade** (D14). What the caller brings is a scene and a
-     * camera, both of which it built; what it gets back is a `Sampler2D`. The frame itself goes
-     * through `Renderer.render_to_target` (D50), so the picture is drawn by the renderer that is
-     * already running, with the geometry and the textures it already holds resident.
-     *
-     * **The renderer is resized for the call and put back afterwards.** Everything a frame is built
-     * out of is sized from the output resolution, so a 64 x 64 picture means a 64 x 64 frame; the
-     * temporal history that costs is dropped either way by the resize.
-     *
-     * @param {Scene} scene
-     * @param {Camera} camera
-     * @param {number} width texels
-     * @param {number} height texels
-     * @returns {Promise<Sampler2D>} RGBA, one byte a channel
-     * @throws {Error} when there is no device — before a successful {@link start}, or after
-     * {@link stop}
-     */
-    async render_to_sampler(scene, camera, width, height) {
-        assert.defined(scene, 'scene');
-        assert.defined(camera, 'camera');
-        assert.isNonNegativeInteger(width, 'width');
-        assert.isNonNegativeInteger(height, 'height');
-        assert.greaterThan(width, 0, 'width');
-        assert.greaterThan(height, 0, 'height');
-
-        const renderer = this.#renderer;
-
-        if (renderer === null) {
-            throw new Error('cannot render without a device — start() has not run, or stop() has');
-        }
-
-        const target = renderer.graphics.textures.contextFromDescriptor(TextureDescriptor.from({
-            label: "GraphicsEngine3/offscreen",
-            size: [width, height, 1],
-            format: OFFSCREEN_FORMAT,
-            usage: GPUTextureUsage.RENDER_ATTACHMENT
-                | GPUTextureUsage.TEXTURE_BINDING
-                | GPUTextureUsage.COPY_SRC
-        }));
-
-        const pixel_ratio = renderer.pixel_ratio;
-        const automatic_exposure = renderer.feature_automatic_exposure_enabled;
-
-        try {
-            renderer.pixel_ratio = 1;
-            renderer.resize(width, height);
-
-            /*
-             A picture of one object against nothing has no scene to read an exposure off, and an
-             adapting one would take the frames it adapts over — so a preview is drawn at the fixed
-             exposure instead, which is what a studio light rig is for.
-            */
-            renderer.feature_automatic_exposure_enabled = false;
-
-            for (let i = 0; i < OFFSCREEN_FRAMES; i++) {
-                renderer.render_to_target(camera, scene, 1 / 60, target);
-            }
-
-            const data = await target.download();
-
-            return new Sampler2D(data, 4, width, height);
-        } finally {
-            target.destroy();
-
-            renderer.feature_automatic_exposure_enabled = automatic_exposure;
-            renderer.pixel_ratio = pixel_ratio;
-
-            this.updateSize();
-        }
-    }
-
-    /**
-     * Whether there is a device to render with.
-     *
-     * @returns {boolean}
-     */
-    get is_running() {
-        return this.#renderer !== null;
-    }
-
-    /**
-     * Stand a device up and attach its canvas to the viewport.
-     *
-     * Asynchronous because acquiring a WebGPU device is — there is no synchronous form of it — and
-     * because failing to get one is a normal outcome that has to be reported rather than thrown
-     * into a constructor. A failure raises `on.contextFailed` with a message written for a person
-     * and rethrows, so a caller that wants to handle it can and one that does not still fails
-     * loudly.
-     *
-     * @returns {Promise<void>}
-     */
-    async start() {
-        if (this.#renderer !== null) {
-            // already running; starting twice is a caller error rather than a no-op worth hiding
-            throw new Error('GraphicsEngine3 is already started');
-        }
-
-        const canvas = document.createElement("canvas");
-
-        canvas.classList.add("graphics-engine-render-canvas");
-
-        const style = canvas.style;
-
-        style.userSelect = style.webkitUserSelect = style.mozUserSelect = "none";
-        // see https://www.w3.org/TR/pointerevents/#the-touch-action-css-property
-        style.touchAction = "none";
-
-        this.#canvas = canvas;
-
-        const renderer = new Renderer();
-
-        try {
-            await renderer.initialize({ context: canvas.getContext('webgpu') });
-        } catch (failure) {
-            this.#canvas = null;
-
-            this.on.contextFailed.send1(failure);
-
-            throw failure;
-        }
-
-        renderer.onDeviceFailure.add(this.#handle_device_failure, this);
-
-        // Extensions outlive the device: they are registered against the engine, not against a
-        // renderer that a restart replaces. This is what makes a system able to register once, at
-        // startup, without knowing whether a device exists yet.
-        for (let i = 0; i < this.#extensions.length; i++) {
-            renderer.add_extension(this.#extensions[i]);
-        }
-
-        this.#renderer = renderer;
-        this.domElement = canvas;
-
-        // Re-point the viewport, and the page with it. This is the wrinkle E1 named: `start` builds
-        // a *new* canvas, so a restart would otherwise leave the dead one mounted and the live one
-        // detached. `View.el` is read unguarded all over the view layer, so it is replaced rather
-        // than cleared — it always holds an element.
-        const previous = this.viewport.el;
-
-        this.viewport.el = canvas;
-
-        if (previous != null && previous.parentNode !== null) {
-            previous.parentNode.replaceChild(canvas, previous);
-        }
-
-        this.updateSize();
-
-        // so the first frame's interval is a real one rather than the whole of the boot
-        this.#last_render_timestamp = performance.now();
-    }
-
-    /**
-     * Tear the device down and let go of the canvas.
-     *
-     * Symmetric with {@link start}, and that symmetry is the point: the old engine started in a
-     * constructor and could not be restarted.
-     */
-    stop() {
-        const renderer = this.#renderer;
-
-        if (renderer === null) {
-            // never started, or stopped twice — nothing to undo
-            return;
-        }
-
-        renderer.onDeviceFailure.remove(this.#handle_device_failure, this);
-        renderer.destroy();
-
-        this.#renderer = null;
-        this.#canvas = null;
-        this.domElement = null;
-
-        // `viewport.el` is deliberately left pointing at the spent canvas rather than cleared: the
-        // view layer reads it without checking, and the next `start` swaps it for a live one.
-    }
-
-    /**
-     * @param {ShadeDeviceFailure} failure
-     */
-    #handle_device_failure(failure) {
-        this.on.contextLost.dispatch(failure);
-    }
-
-    /**
-     * A pointer position in viewport pixels, as a clip-space point.
-     *
-     * Unchanged from the old engine, down to writing into a caller's vector: it is arithmetic on the
-     * viewport size and has nothing to do with which renderer is underneath.
-     *
-     * @param {Vector2|Vector3} input viewport pixels, origin top-left
-     * @param {Vector2|Vector3} result written with −1…1, +Y up
-     */
-    normalizeViewportPoint(input, result) {
-        const size = this.viewport.size;
-
-        // shifted by half a pixel, so the value names the centre of the pixel rather than its corner
-        result.x = ((input.x + 0.5) / size.x) * 2 - 1;
-        result.y = -((input.y + 0.5) / size.y) * 2 + 1;
-    }
-
-    /**
-     * A ray from the eye through a point on the viewport, in world space.
-     *
-     * Same name, same arguments, same meaning as on the old engine — and the same expectation that
-     * `x` and `y` are **clip-space**, which {@link normalizeViewportPoint} is what produces. What is
-     * behind it is Shade's camera rather than three's; see {@link shade_camera_projection_ray}.
-     *
-     * This is the only picking primitive the game actually needs. Every gameplay pick is a terrain
-     * raycast — an exact query against the terrain's own representation, which no part of the renderer
-     * is involved in — so a working ray is the whole of the renderer's contribution to it.
-     *
-     * @param {number} x clip space, −1…1
-     * @param {number} y clip space, −1…1, +Y up
-     * @param {Vector3} source written with the ray's origin
-     * @param {Vector3} direction written with a unit direction
-     */
-    viewportProjectionRay(x, y, source, direction) {
-        shade_camera_projection_ray(this.#camera, x, y, source, direction);
-    }
-
-    /**
-     * Size the drawing buffer to the viewport.
-     *
-     * Shade's `resize` takes a **CSS** size and applies the device pixel ratio itself, which is the
-     * opposite of what the old engine's renderer wanted — so what it is given here is the viewport
-     * size scaled by the engine's own `pixelRatio` and nothing more. `output_resolution` is then
-     * the device-pixel figure, for everything that has to land on the same texel grid.
-     */
-    updateSize() {
-        const size = this.viewport.size;
-        const pixel_ratio = this.pixelRatio.getValue();
-
-        const css_width = max2(0, size.x * pixel_ratio);
-        const css_height = max2(0, size.y * pixel_ratio);
-
-        const renderer = this.#renderer;
-
-        if (renderer !== null) {
-            renderer.resize(css_width, css_height);
-        }
-
-        if (this.domElement !== null) {
-            this.domElement.style.width = size.x + "px";
-            this.domElement.style.height = size.y + "px";
-        }
-
-        const device_pixel_ratio = window.devicePixelRatio;
-
-        // clamped to 1 for the same reason the old engine clamped it: a collapsed viewport still
-        // allocates attachments, and a zero-sized one is not a legal target
-        this.output_resolution.set(
-            max2(1, Math.floor(css_width * device_pixel_ratio)),
-            max2(1, Math.floor(css_height * device_pixel_ratio))
-        );
-    }
-
-    /**
-     * Draw a frame, if there is anything to draw it with.
-     *
-     * @param {number} [time_delta_seconds]
-     * @returns {boolean} whether a frame was submitted
-     */
-    render(time_delta_seconds = 1 / 60) {
-        const renderer = this.#renderer;
-
-        if (renderer === null) {
-            return false;
-        }
-
-        const viewport_size = this.viewport.size;
-
-        if (viewport_size.x <= 0 || viewport_size.y <= 0) {
-            /*
-             There is no surface to draw into. Every boot passes through this — the renderer starts
-             before the game view is laid out — and so does any collapsed or unmounted view.
-             Drawing anyway is worse than drawing nothing: `output_resolution` and the renderer's
-             own resolutions both floor at one texel, and a one-texel target is a size the frame's
-             mip chains cannot be built from, so what a frame produces here is a run of invalid
-             textures rather than a picture. `needDraw` is left set, so the next frame retries.
-            */
-            return false;
-        }
-
-        /*
-         The **refresh** interval, measured here rather than taken from `time_delta_seconds`. What
-         the controller steers by has to be how long a frame actually took, wall clock, including
-         everything outside this call; the argument is the simulation's delta, which is clamped and
-         is not the same quantity. Measuring between calls is also what makes this correct for any
-         driver — the engine's animation frame, or a probe calling `render` directly.
-        */
-        const now = performance.now();
-
-        this.#dynamic_resolution.notify_frame((now - this.#last_render_timestamp) / 1000);
-
-        this.#last_render_timestamp = now;
-
-        // Aspect follows the surface being drawn to, so it is refreshed here rather than left to
-        // whoever last resized: a camera describing a viewport that has since changed shape is the
-        // classic source of a stretched frame.
-        this.#camera.aspect = renderer.aspect_ratio;
-        this.#camera.update();
-
-        this.on.preRender.dispatch();
-
-        const submitted = renderer.render(this.#camera, this.#scene, time_delta_seconds);
-
-        this.frameIndex++;
-        this.needDraw = false;
-
-        this.on.postRender.dispatch();
-
-        return submitted;
-    }
-}
+export const GraphicsEngine3 = GraphicsEngine;