@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/ui/world-panel/panel.d.ts

@@ -0,0 +1,235 @@
+/**
+ * World panels (ws/ui-world-panel): a Canvas2D-painted texture on a quad in the scene, with the
+ * engine's widgets and theme, hit by the pointer router's rays. Flat screens on walls, a wrist
+ * menu in VR, a head-locked HUD: anything a DOM overlay cannot be because it must sit in depth.
+ *
+ * - The canvas is `width × resolution` by `height × resolution` px; widgets are laid out and hit
+ *   in those px. Only the dirty rect is repainted and uploaded, at most once per frame, in
+ *   `prepare`; a frame with nothing dirty uploads nothing.
+ * - The quad is drawn by `draw` inside the scene pass (`frame.drawable(panel)`), depth-tested by
+ *   default; a head-locked panel defaults to `depthTest: false` so the scene never cuts it.
+ * - Pointers: `hitTest(ray)` gives panel px; `worldPanelTarget(panel)` is the router's tester;
+ *   `poll(router.pointers)` drives hover, press and release from the router each tick, or call
+ *   `pointerDown/Move/Up` yourself. Focus walks `focusNext/Prev`, `activate` and `key`.
+ */
+import type { PointerRouter, RoutedPointer } from '../../input/pointer-router.js';
+import { type HitTester, type Ray } from '../../input/rays.js';
+import type { Camera } from '../../render/camera.js';
+import type { Drawable, Frame } from '../../render/frame.js';
+import type { Renderer } from '../../render/renderer.js';
+import type { Texture } from '../../render/texture.js';
+import { Transform } from '../../render/transform.js';
+import type { ThemeTokens } from '../theme.js';
+import { Painter, type PanelCanvas, type PanelTheme } from './paint.js';
+import type { PanelKeyEvent, WorldWidget, WorldWidgetHost } from './widgets.js';
+/** What `attach` needs from the input (`Input` from `@thunderclap-engine/engine/input` fits). */
+export interface WorldPanelInput {
+    /** The input's pointer router, or null when it has none (`Input.pointers`, ws/api-core). */
+    readonly pointers?: PointerRouter<unknown> | null;
+    /** Called after every `update()`; returns the remover. */
+    onUpdated(fn: () => void): () => void;
+}
+export interface WorldPanelOptions {
+    /** Panel size in world units. */
+    width: number;
+    height: number;
+    /** Canvas px per world unit. Default 256. */
+    resolution?: number;
+    /** Theme tokens over the CSS-px theme (`cssPxTheme`): colours, fonts, spacing. */
+    theme?: Partial<ThemeTokens>;
+    /** `panel` (default): the surface colour with a border. `transparent`: widgets only. */
+    background?: 'panel' | 'transparent';
+    /** Turn to face the camera every `update(camera)`, keeping the position. */
+    billboard?: boolean;
+    /** Follow the camera: `distance` ahead of the eye, `offset` in view units (x right, y up). */
+    headLocked?: {
+        distance: number;
+        offset?: [number, number];
+    };
+    /** Depth test against the scene. Default `true`; `false` for a head-locked panel. */
+    depthTest?: boolean;
+    /** The canvas to paint into (tests); default an `OffscreenCanvas` or a `<canvas>`. */
+    canvas?: PanelCanvas;
+    label?: string;
+}
+/** `hitTest`'s result: panel px from the top-left, the widget there (or `null`), the ray's distance. */
+export interface WorldPanelHit {
+    x: number;
+    y: number;
+    widget: WorldWidget | null;
+    /** World units along the ray. */
+    distance: number;
+}
+export interface WorldPanelStats {
+    /** Paints of a dirty rect. */
+    repaints: number;
+    /** Texture uploads (at most one per `prepare`). */
+    uploads: number;
+    /** Bytes uploaded in all (dirty rect × 4). */
+    bytes: number;
+}
+export declare class WorldPanel implements Drawable, WorldWidgetHost {
+    readonly transform: Transform;
+    /** Panel size in world units. */
+    readonly width: number;
+    readonly height: number;
+    readonly resolution: number;
+    /** Canvas size in px. */
+    readonly pxWidth: number;
+    readonly pxHeight: number;
+    readonly texture: Texture;
+    readonly canvas: PanelCanvas;
+    readonly painter: Painter;
+    readonly theme: PanelTheme;
+    readonly stats: WorldPanelStats;
+    /** Resolves when `document.fonts` is ready (at once without it); the panel repaints then. */
+    readonly fontLoaded: Promise<void>;
+    /** Draw this in the scene: `frame.drawable(panel.drawable)` (it is the panel itself). */
+    readonly drawable: Drawable;
+    readonly label: string;
+    depthTest: boolean;
+    /** Widgets in flow order. */
+    readonly widgets: WorldWidget[];
+    /** The focused widget, or `null`. */
+    focused: WorldWidget | null;
+    /** The widget under the last moved pointer, or `null`. */
+    hovered: WorldWidget | null;
+    /** Draws issued by the last `draw` (0 or 1). */
+    draws: number;
+    private readonly device;
+    private readonly background;
+    private readonly billboard;
+    private readonly headLocked;
+    private readonly dirtyRect;
+    private layoutDirty;
+    private needsUpload;
+    private disposed;
+    /** The press: which widget holds it, by pointer id. */
+    private readonly presses;
+    private pressCount;
+    private readonly tracked;
+    private nextTrackedId;
+    private readonly uniform;
+    private readonly uniformData;
+    private readonly uniformSent;
+    private uniformDirty;
+    private readonly group;
+    private readonly renderer;
+    private readonly pipelineDesc;
+    /**
+     * Pipelines per (depth format, target aux key) (ws/core-8): a panel drawn into
+     * `renderer.target` with aux attachments and into a plain target (an XR eye, a probe) in the
+     * same frame binds the variant whose colour targets match each pass.
+     */
+    private readonly pipelines;
+    private readonly localRay;
+    private readonly hit;
+    private readonly routerHit;
+    private readonly routerNormal;
+    private readonly basis;
+    private detachFn;
+    constructor(renderer: Renderer, opts: WorldPanelOptions);
+    /** Whether a repaint or an upload is pending. */
+    get dirty(): boolean;
+    /** Append a widget to the flow (or place it at its `rect`). */
+    add<W extends WorldWidget>(widget: W): W;
+    remove(widget: WorldWidget): void;
+    /** @internal `WorldWidgetHost` */
+    invalidate(widget: WorldWidget): void;
+    /** @internal `WorldWidgetHost`: re-run the flow and repaint everything next frame. */
+    relayout(): void;
+    private markAllDirty;
+    private readonly ring;
+    /** `r` grown by the focus ring, so a focus change repaints the ring too. */
+    private ringRect;
+    private layout;
+    /** The widget at panel px, or `null`. Explicit-rect widgets later in the list win. */
+    widgetAt(x: number, y: number): WorldWidget | null;
+    /**
+     * Paint what is dirty now (the layout if it changed, then the dirty rect) and queue the upload.
+     * `prepare` calls this; call it yourself to paint ahead of the frame.
+     */
+    repaint(): void;
+    private readonly uploadRect;
+    /**
+     * Per frame, before drawing: a head-locked panel moves in front of `camera`, a billboard turns
+     * to face it. A plain panel ignores it.
+     */
+    update(camera: Camera): void;
+    /**
+     * Where `ray` (world space) meets the panel's plane: px from the top-left (outside the quad
+     * allowed) and the distance along the ray, written to `this.hit`. False when the ray is
+     * parallel to the plane, points away from it, or the transform is singular.
+     */
+    private project;
+    /**
+     * Where `ray` (world space) meets the panel: px from the top-left, the widget there and the
+     * distance along the ray; `null` when it misses. The result object is reused.
+     */
+    hitTest(ray: Ray): WorldPanelHit | null;
+    /** A `HitTester` for the pointer router whose hit's `target` is this panel. */
+    tester(): HitTester<WorldPanel>;
+    private setHover;
+    /** A pointer is over panel px (`x`, `y`); `id` tells pointers apart (default 0). */
+    pointerMove(x: number, y: number, id?: number): void;
+    /** The pointer left the panel (no widget is hovered; a held press stays until `pointerUp`). */
+    pointerLeave(id?: number): void;
+    /** A press at panel px: the widget there takes it (and focus when focusable). */
+    pointerDown(x: number, y: number, id?: number): void;
+    /**
+     * The press `id` ends at panel px (outside the quad allowed); a release over the pressed widget
+     * activates it. `NaN` coordinates cancel: the widget hears a release that is nowhere.
+     */
+    pointerUp(x: number, y: number, id?: number): void;
+    /** Wheel over panel px: the widget there scrolls. Returns whether something used it. */
+    wheel(x: number, y: number, dy: number): boolean;
+    /**
+     * Drive the panel from the router's live pointers once per tick (after `input.update()`): a
+     * pointer whose nearest hit is this panel hovers, its `select` edge presses and releases; one
+     * that left releases outside. Pass `router.pointers` (or any array of `RoutedPointer`).
+     */
+    poll(pointers: readonly RoutedPointer[]): void;
+    private trackedFor;
+    /** `router.addTester(panel.tester())`; returns the remover. */
+    attachTo(router: PointerRouter<unknown>): () => void;
+    /**
+     * Drive the panel on the input tick (ws/ui-4): registers the panel's tester with the input's
+     * pointer router and, through `input.onUpdated`, calls `poll(router.pointers)` after every
+     * `input.update()` and `update(camera)` with the router's camera (the one the rays go through,
+     * `renderer.camera` in a game, the head camera while `ctx.xr` is active). `opts.camera`
+     * (ws/api-core) names another camera to face, read each tick. Call once; `detach()` (and
+     * `dispose()`) undoes it. Manual `poll`/`update` still work for an input without a router.
+     */
+    attach(input: WorldPanelInput, opts?: {
+        camera?: () => Camera | null;
+    }): void;
+    /** Stop following the input `attach` hooked; nothing without one. */
+    detach(): void;
+    /** Focus `widget` (`null` clears); a widget that is not focusable is ignored. */
+    focus(widget: WorldWidget | null): void;
+    private focusStep;
+    /** Focus the next focusable widget (wrapping); the first when none is focused. */
+    focusNext(): WorldWidget | null;
+    /** Focus the previous focusable widget (wrapping); the last when none is focused. */
+    focusPrev(): WorldWidget | null;
+    /** Activate the focused widget (a button presses, a toggle flips). */
+    activate(): void;
+    /**
+     * A keyboard event: Tab / Shift+Tab move focus, Enter and Space activate, arrows and the rest
+     * go to the focused widget. Returns whether the key was consumed.
+     */
+    key(event: PanelKeyEvent): boolean;
+    /** Repaint what is dirty and upload it (once) before the pass. */
+    prepare(_encoder: GPUCommandEncoder, _frame?: Frame): void;
+    /** Draw the quad inside the scene pass, with the pipeline for its depth format and aux key. */
+    draw(pass: GPURenderPassEncoder, frame?: Frame): void;
+    private pipelineFor;
+    /** Release the texture and buffers; the panel draws nothing after. */
+    dispose(): void;
+    /** Whether a press is held on some widget. */
+    get pressing(): boolean;
+}
+/** `new WorldPanel(renderer, opts)`. */
+export declare function createWorldPanel(renderer: Renderer, opts: WorldPanelOptions): WorldPanel;
+/** The pointer router's `HitTester` for `panel`: `router.addTester(worldPanelTarget(panel))`. */
+export declare function worldPanelTarget(panel: WorldPanel): HitTester<WorldPanel>;