@woosh/meep-engine 3.11.3 → 3.12.0

package/src/engine/graphics3/GraphicsEngine.d.ts

@@ -0,0 +1,340 @@
+/**
+ * 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 GraphicsEngine {
+    /**
+     * 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(): boolean;
+    /**
+     * Danger zone.
+     * Be careful with what you do, with great Renderer comes great responsibility.
+     * @returns {Renderer|null}
+     */
+    get renderer(): Renderer;
+    /**
+     * 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}
+     */
+    camera: ShadeCameraAdapter;
+    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: 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: Signal;
+        /**
+         * The GPU device was lost. Nothing renders after this.
+         *
+         * @type {Signal}
+         */
+        contextLost: 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: any;
+        /**
+         * 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: any;
+    };
+    /**
+     * @type {Vector1}
+     */
+    pixelRatio: Vector1;
+    /**
+     * Final render resolution in whole device pixels. Zero until the viewport has a size.
+     *
+     * @readonly
+     * @type {Vector2}
+     */
+    readonly output_resolution: Vector2;
+    /**
+     * 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}
+     */
+    viewport: EmptyView;
+    /**
+     * @type {HTMLCanvasElement|null}
+     */
+    domElement: HTMLCanvasElement | null;
+    /**
+     * Whether the next frame has anything new to show. With {@link autoDraw} off, this is what
+     * gates rendering at all.
+     *
+     * @type {boolean}
+     */
+    needDraw: boolean;
+    /**
+     * 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}
+     */
+    autoDraw: boolean;
+    /**
+     * @type {number}
+     */
+    frameIndex: number;
+    /**
+     * 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(): DynamicResolutionScaling;
+    /**
+     * 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: Scene): void;
+    /**
+     * 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: ShadeTexture): void;
+    /**
+     * 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: RenderExtension): RenderExtension;
+    /**
+     * 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: FramePhase): number;
+    /**
+     * 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: RenderExtension): boolean;
+    /**
+     * 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: Scene): GPUSceneContext | null;
+    /**
+     * 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}
+     */
+    render_to_sampler(scene: Scene, camera: Camera, width: number, height: number): Promise<Sampler2D>;
+    /**
+     * Whether there is a device to render with.
+     *
+     * @returns {boolean}
+     */
+    get is_running(): boolean;
+    /**
+     * 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>}
+     */
+    start(): Promise<void>;
+    /**
+     * 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(): void;
+    /**
+     * 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: Vector2 | Vector3, result: Vector2 | Vector3): void;
+    /**
+     * 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: number, y: number, source: Vector3, direction: Vector3): void;
+    /**
+     * 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(): void;
+    /**
+     * 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?: number): boolean;
+    #private;
+}
+import { Renderer } from "../../shade/renderer/Renderer.js";
+import { ShadeCameraAdapter } from "./ShadeCameraAdapter.js";
+import Signal from "../../core/events/signal/Signal.js";
+import Vector1 from "../../core/geom/Vector1.js";
+import { Vector2 } from "../../core/geom/Vector2.js";
+import EmptyView from "../../view/elements/EmptyView.js";
+import { DynamicResolutionScaling } from "../../shade/renderer/DynamicResolutionScaling.js";
+import { Scene } from "../../shade/renderer/scene/Scene.js";
+import { Sampler2D } from "../graphics/texture/sampler/Sampler2D.js";
+//# sourceMappingURL=GraphicsEngine.d.ts.map

package/src/engine/graphics3/GraphicsEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphicsEngine.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GraphicsEngine.js"],"names":[],"mappings":"AAkDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IACI;;;;;OAKG;IACH,gCAEC;IAUD;;;;OAIG;IACH,yBAEC;IA0DG;;;;;;OAMG;IACH,QAFU,kBAAkB,CAEsB;IAElD;QACI;;;;;;;;WAQG;mBADO,MAAM;QAIhB;;;;;WAKG;oBADO,MAAM;QAIhB;;;;WAIG;qBADO,MAAM;QAIhB;;;;;;;WAOG;;QAGH;;;;;WAKG;;MAEN;IAED;;OAEG;IACH,YAFU,OAAO,CAEe;IAEhC;;;;;OAKG;IACH,4BAFU,OAAO,CAEyB;IAE1C;;;;;;OAMG;IACH,UAFU,SAAS,CAEY;IAG/B;;OAEG;IACH,YAFU,iBAAiB,GAAC,IAAI,CAEV;IAEtB;;;;;OAKG;IACH,UAFU,OAAO,CAEG;IAEpB;;;;;OAKG;IACH,UAFU,OAAO,CAEG;IAEpB;;OAEG;IACH,YAFU,MAAM,CAEG;IAoBvB;;;;;;;;;;;;OAYG;IACH,mDAEC;IAED;;;;;;;;OAQG;IACH,iBAFW,KAAK,QAoBf;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,iDAOC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,2DAWC;IAED;;;;;;;;;;OAUG;IACH,oCAFa,MAAM,CAclB;IAED;;;;;;OAMG;IACH,8CAFa,OAAO,CAgBnB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,qBALW,KAAK,GACH,kBAAgB,IAAI,CAehC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,yBARW,KAAK,yBAEL,MAAM,UACN,MAAM,GACJ,QAAQ,SAAS,CAAC,CAwD9B;IAED;;;;OAIG;IACH,0BAEC;IAED;;;;;;;;;;OAUG;IACH,SAFa,QAAQ,IAAI,CAAC,CA4DzB;IAED;;;;;OAKG;IACH,aAiBC;IASD;;;;;;;;OAQG;IACH,8BAHW,OAAO,UAAQ,UACf,OAAO,UAAQ,QAQzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,yBALW,MAAM,KACN,MAAM,6CAMhB;IAED;;;;;;;OAOG;IACH,mBA0BC;IAED;;;;;OAKG;IACH,4BAHW,MAAM,GACJ,OAAO,CAoDnB;;CACJ;yBA7wBwB,kCAAkC;mCAMxB,yBAAyB;mBAbzC,oCAAoC;oBACnC,4BAA4B;wBACxB,4BAA4B;sBAQ9B,kCAAkC;yCAJf,kDAAkD;sBAErE,qCAAqC;0BACjC,0CAA0C"}