@woosh/meep-engine 3.11.2 → 3.12.0

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

@@ -1,340 +1,10 @@
 /**
- * The renderer meep 3 talks to: Shade behind the shape `GraphicsEngine` presented.
+ * @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.
  *
- * 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).
+ * 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.
  */
-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(): 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";
+export const GraphicsEngine3: typeof GraphicsEngine;
+import { GraphicsEngine } from "./GraphicsEngine.js";
 //# sourceMappingURL=GraphicsEngine3.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"GraphicsEngine3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GraphicsEngine3.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"}
+{"version":3,"file":"GraphicsEngine3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GraphicsEngine3.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,oDAA8C;+BATf,qBAAqB"}