@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/render/camera.d.ts

@@ -0,0 +1,302 @@
+import { type Mat4 } from '../core/math.js';
+/** A rectangle: origin at top-left, y down. Matches `platform`'s and `ui`'s `Rect`. */
+export interface CameraRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A point; `worldToScreen` and `screenToWorld` fill one. */
+export interface CameraPoint {
+    x: number;
+    y: number;
+    z: number;
+}
+/** Every layer bit set: the default `Camera.layers`. */
+export declare const ALL_LAYERS = 4294967295;
+/**
+ * Half the depth range of `Camera.ortho2d`, in design units: its near plane is at world
+ * z = -ORTHO2D_HALF_DEPTH, the far plane at +ORTHO2D_HALF_DEPTH, z = 0 at clip depth 0.5.
+ */
+export declare const ORTHO2D_HALF_DEPTH = 1024;
+/**
+ * Floats in the WGSL `EngineCamera` block: 112 used (`jitter` ends at byte 448), padded
+ * to 512 bytes so the lights block that follows it in the view's uniform buffer stays on a
+ * 256-byte boundary (`minUniformBufferOffsetAlignment`).
+ */
+export declare const CAMERA_BLOCK_FLOATS = 128;
+/** Float offset of `inv_view_proj` inside the camera block (byte 240). */
+export declare const CAMERA_INV_VIEW_PROJ_OFFSET = 60;
+/** Float offset of `prev_view_proj` (last frame's unjittered `view_proj`) inside the block. */
+export declare const CAMERA_PREV_VIEW_PROJ_OFFSET = 76;
+/** Float offset of `prev_view` (last frame's `view`) inside the block. */
+export declare const CAMERA_PREV_VIEW_OFFSET = 92;
+/** Float offset of `jitter` (clip-space dx, dy; the pixel offset x, y) inside the block. */
+export declare const CAMERA_JITTER_OFFSET = 108;
+/** Floats in `Camera.frustum`: six planes × (a, b, c, d). */
+export declare const FRUSTUM_FLOATS = 24;
+/**
+ * A view-projection camera. Matrices are column-major `Float32Array(16)` (see `mat4` in
+ * `@thunderclap-engine/engine/core`), computed on read and cached until something changes.
+ *
+ * Two presets:
+ *
+ * - `Camera.ortho2d(designW, designH)`: 1 world unit = 1 design px, origin top-left, y down,
+ *   z into the screen (right-handed with y down): world z in `±ORTHO2D_HALF_DEPTH` spans the
+ *   depth buffer, z = 0 sits at clip depth 0.5 and larger z is farther. The 2D controls `x`,
+ *   `y`, `zoom` and `rotation` move it over that space exactly like the engine's earlier 2D
+ *   camera; `fitRect` frames a world rect.
+ *   `Transform.z` is thus a stacking axis for 2D draws under a depth camera.
+ * - `Camera.perspective(fovY, aspect, near, far)`: right-handed, looking down -z; place it with
+ *   `lookAt` or `setView`.
+ *
+ * `screen` is the rect the clip space spans, in the units `worldToScreen` returns and
+ * `screenToWorld` takes: the logical (design px) space for `ortho2d`, normalised 0..1 for
+ * `perspective` until a caller sets it.
+ *
+ * ```ts
+ * const cam = renderer.camera;          // Camera.ortho2d(1920, 1080) by default
+ * cam.x = 120; cam.zoom = 1.5;          // pan and zoom, as before
+ * const p = cam.screenToWorld(tapX, tapY); // logical px (surface.clientToLogical) → world
+ * ```
+ */
+export declare class Camera {
+    /** Depth test for draws through this camera. The 2D preset leaves it off. */
+    depthTest: boolean;
+    /** Depth write for draws through this camera. The 2D preset leaves it off. */
+    depthWrite: boolean;
+    /**
+     * Layer membership mask (u32): a draw is seen when `draw.layers & camera.layers` is nonzero.
+     * Default: every bit. Draw order within a camera is a separate sort key, not this mask.
+     */
+    layers: number;
+    /** The rect clip space spans, in screen units (see the class comment). */
+    readonly screen: CameraRect;
+    /**
+     * The `view_index` the camera block carries (u32): 0 by default; a stereo pair sets 0 and 1
+     * so a material can tell the eyes apart. The renderer writes it as given, whatever the order
+     * of the frame's `render` calls.
+     */
+    viewIndex: number;
+    /**
+     * Frustum-cull mesh draws through this camera: a draw whose bounding sphere (`mesh.bounds`
+     * through its instance matrix) lies outside any plane of `frustum` is skipped before the sort
+     * and counted in `renderer.stats.culled`. Off for `ortho2d` (the 2D path is untouched), on
+     * for `perspective`. Sprites and meshes without bounds are never culled.
+     */
+    cull: boolean;
+    /**
+     * Scales the projected size the renderer picks `MeshLod` levels by (ws/render-5): above 1
+     * keeps finer levels farther out, below 1 drops to coarser ones sooner. Default 1.
+     */
+    lodBias: number;
+    /**
+     * Last frame's unjittered `viewProjection`, copied by the renderer at the start of each view
+     * it draws this camera through (`recordHistory`), before the camera is read; identity until
+     * the first frame. What a reprojecting post pass (TAA, motion blur) reads through
+     * `PostInputs.view.previousViewProj`. Read-only (`Float32Array(16)`).
+     */
+    readonly previousViewProj: Mat4;
+    /** Last frame's `view`, kept like `previousViewProj`. Read-only. */
+    readonly previousView: Mat4;
+    private readonly viewM;
+    /** `viewProjM` before the jitter offset (what `previousViewProj` and the frustum use). */
+    private readonly steadyViewProjM;
+    /** What the last `recordHistory` saw: the matrices the next one moves into `previous*`. */
+    private readonly historyViewProjM;
+    private readonly historyViewM;
+    private hasHistory;
+    /** Sub-pixel jitter in pixels of the current target (`setJitter`). */
+    private jitterX;
+    private jitterY;
+    /** The target size the jitter is measured against; 0 × 0 (the default) applies none. */
+    private jitterW;
+    private jitterH;
+    private readonly projM;
+    private readonly viewProjM;
+    private readonly invViewProjM;
+    private readonly invViewM;
+    private readonly pos;
+    /** 'view2d': the view comes from x/y/zoom/rotation; 'custom': from setView/lookAt. */
+    private viewSource;
+    /** 'ortho2d': design-space ortho; 'custom': setProjection/setPerspective. */
+    private projSource;
+    private designW;
+    private designH;
+    private _x;
+    private _y;
+    private _zoom;
+    private _rotation;
+    private dirty;
+    private invDirty;
+    private posDirty;
+    private frustumDirty;
+    private readonly frustumM;
+    /** 1 world unit = 1 design px over a `designW × designH` space, origin top-left, y down. */
+    static ortho2d(designW: number, designH: number): Camera;
+    /**
+     * Perspective camera at the origin looking down -z. `fovY` in radians; `far` may be
+     * `Infinity`. Depth test, depth write and frustum culling are on (`setPerspective` sets them).
+     */
+    static perspective(fovY: number, aspect: number, near: number, far: number): Camera;
+    /**
+     * Switch to the 2D preset over `designW × designH` (resets `screen` to that space; keeps the
+     * 2D controls). Depth flags are left as they are.
+     */
+    setOrtho2d(designW: number, designH: number): this;
+    /**
+     * Replace the projection with a perspective one (radians; `far` may be `Infinity`) and
+     * configure the camera the way `Camera.perspective` does: `depthTest`, `depthWrite` and
+     * `cull` on (ws/camera-ergo). The view is untouched, so `cam.setPerspective(...)` on a
+     * default camera renders like `Camera.perspective(...)`; `setProjection` stays raw.
+     */
+    setPerspective(fovY: number, aspect: number, near: number, far: number): this;
+    /** Replace the projection matrix (copied). Raw: no depth or cull flag changes. */
+    setProjection(m: ArrayLike<number>): this;
+    /** Replace the view matrix (copied). The 2D controls stop applying until `setOrtho2d`. */
+    setView(m: ArrayLike<number>): this;
+    /**
+     * Replace the view matrix (copied); the same as `setView`, named for an XR eye whose
+     * `XRView.transform.inverse.matrix` is handed over as-is each frame (ws/xr).
+     */
+    setViewMatrix(m: ArrayLike<number>): this;
+    /** Place the camera at `eye` looking at `target` (`up` defaults to +y). */
+    lookAt(eye: ArrayLike<number>, target: ArrayLike<number>, up?: ArrayLike<number>): this;
+    /** 2D pan (design px): the world point at the view centre is `designW/2 + x`. */
+    get x(): number;
+    set x(v: number);
+    /** 2D pan (design px). */
+    get y(): number;
+    set y(v: number);
+    /** 2D zoom about the view centre. */
+    get zoom(): number;
+    set zoom(v: number);
+    /** 2D view rotation about the view centre, radians (the view turns clockwise, the world counter-clockwise). */
+    get rotation(): number;
+    set rotation(v: number);
+    /**
+     * Frame the world rect `rect` (z = 0) into `viewport` (screen units; default `screen`),
+     * contained and centred, with rotation reset. Needs the 2D view (`ortho2d`); for the
+     * world space a layout leaves, convert `layout.freeRect` to screen units first.
+     */
+    fitRect(rect: CameraRect, viewport?: CameraRect): this;
+    /**
+     * `fitRect` into the part of the surface a layout leaves free: `free` is in CSS px relative to
+     * the surface's parent (`ui.layout.freeRect`), `surface.rect` is where the canvas sits in the
+     * same CSS px (`Surface.rect`); the free rect is mapped onto `screen` (its share of the canvas)
+     * and the world rect is fitted into that. Allocates nothing.
+     */
+    fitFreeRect(rect: CameraRect, free: CameraRect, surface: {
+        readonly rect: CameraRect;
+    }): this;
+    /** World → view. Read-only; change it with the 2D controls, `setView` or `lookAt`. */
+    get view(): Mat4;
+    /** View → clip. Read-only; change it with a preset or `setProjection`. */
+    get projection(): Mat4;
+    /** World → clip (`projection × view`). Read-only. */
+    get viewProjection(): Mat4;
+    /** The eye position in world space (from the inverse view). Read-only. */
+    get position(): Float32Array;
+    /**
+     * Clip → world (`viewProjection⁻¹`), column-major like `viewProj`; cached and recomputed
+     * lazily after any view or projection change. Identity when `viewProjection` is singular.
+     * Read-only.
+     */
+    get invViewProj(): Mat4;
+    /**
+     * Offset the projection by `(x, y)` pixels of the current target (a TAA sample sequence):
+     * `viewProjection` and `invViewProj` carry it, `previousViewProj` and the frustum never do.
+     * Zero by default. The renderer applies it only when its post processor declares
+     * `wantsJitter` (and never through the 2D `ortho2d` projection), so a page without one
+     * draws exactly as before. +x moves the image right, +y down.
+     */
+    setJitter(x: number, y: number): this;
+    /** `setJitter(0, 0)`. */
+    clearJitter(): this;
+    /** The jitter set by `setJitter`, in pixels: `[x, y]`. */
+    get jitter(): [number, number];
+    /** `jitter` into `out` (no allocation): the pixels applied, `0, 0` when not applied. */
+    getJitter(out: [number, number] | Float32Array): void;
+    /**
+     * The target size the jitter applies against (0 × 0 ignores it). Engine-internal: the
+     * renderer sets it per view from the viewport when the post processor wants jitter.
+     */
+    setJitterTarget(width: number, height: number): void;
+    /** The clip-space offset the current jitter adds: `[dx, dy]` (0 when not applied). */
+    jitterClip(out: [number, number] | Float32Array): void;
+    /**
+     * Move the (unjittered) `viewProjection` and `view` seen by the last call into
+     * `previousViewProj` and `previousView`, and remember the current ones for the next call.
+     * Engine-internal: the renderer calls it at the start of each view, before reading the
+     * camera, so a post pass sees last frame's matrices beside this frame's. The first call
+     * (a camera's first view) sets previous = current: no motion.
+     */
+    recordHistory(): void;
+    /** Is a draw with layer mask `mask` seen by this camera? */
+    sees(mask: number): boolean;
+    /**
+     * View-space depth of a world point: its distance along the view axis, positive in front of
+     * the eye. Reads the view matrix's third row and negates it (`perspective` and `lookAt`
+     * look down -z). `ortho2d` looks down +z, so there it is `-worldZ` at rest. Allocates nothing.
+     */
+    viewZ(x: number, y: number, z?: number): number;
+    /**
+     * `worldToScreen` for many points without the per-point object: reads `count` points from
+     * `points` (x, y, z at `i * stride`; `stride` ≥ 3, default 3, `count` defaults to what fits)
+     * and writes screen x, screen y and clip depth as 3 floats per point at `out[i * 3]`, the
+     * same values `worldToScreen` returns. Returns how many landed inside the viewport: in
+     * front of the eye, within `screen` and with clip depth in 0..1. Allocates nothing.
+     */
+    projectMany(points: ArrayLike<number>, out: Float32Array, count?: number, stride?: number): number;
+    /**
+     * The eight world-space corners of the view frustum into `out` (24 floats, x y z each):
+     * near plane first, then far, each as bottom-left, bottom-right, top-right, top-left in
+     * clip space (clip depth 0 then 1, through `invViewProj`). With `far = Infinity` the far
+     * corners have no finite position (w = 0) and come back as the undivided homogeneous
+     * coordinates, which are directions. Allocates nothing.
+     */
+    frustumCorners(out: Float32Array): Float32Array;
+    /**
+     * World point → screen units (see `screen`); `z` of the result is clip depth (0 near, 1
+     * far). Pass `out` to avoid allocating.
+     */
+    worldToScreen(x: number, y: number, z?: number, out?: CameraPoint): CameraPoint;
+    /**
+     * Screen point (screen units) → world, at clip depth `depth` (0 = near plane, which for
+     * `ortho2d` is world z = -ORTHO2D_HALF_DEPTH; 0.5 is z = 0). Call it at depth 0 and 1 for
+     * a pick ray. Pass `out` to avoid allocating.
+     */
+    screenToWorld(sx: number, sy: number, depth?: number, out?: CameraPoint): CameraPoint;
+    /**
+     * Screen point (screen units) → the world point on the plane z = 0 under it (ws/api-render),
+     * the 2D pick: a tap on an `ortho2d` or tilted camera lands on the sprites' plane with no
+     * depth to choose. A ray parallel to the plane gives the near-plane point. Writes `out`.
+     */
+    screenToWorld(sx: number, sy: number, out: CameraPoint): CameraPoint;
+    /** The pick ray through a screen point, met with the plane z = 0. No allocation. */
+    private screenToPlane;
+    /**
+     * Write the WGSL `EngineCamera` block (`CAMERA_BLOCK_FLOATS` floats) at float offset `o`:
+     * `view`, `proj`, `view_proj`, `camera_pos`, `viewport` (target px: x, y, w, h),
+     * `view_index`, at `CAMERA_INV_VIEW_PROJ_OFFSET` `inv_view_proj`, then `prev_view_proj`,
+     * `prev_view` and `jitter` (clip dx, dy, pixel x, y). `u32` must view the same buffer as
+     * `f32`. Engine-internal.
+     */
+    writeBlock(f32: Float32Array, u32: Uint32Array, o: number, viewport: CameraRect, viewIndex?: number): void;
+    /**
+     * The six frustum planes of `viewProjection` as `FRUSTUM_FLOATS` (24) floats: left, right,
+     * bottom, top, near, far, each `(a, b, c, d)` with a unit normal pointing inside, so a point
+     * `p` is inside when `a·x + b·y + c·z + d >= 0` on every plane and a sphere of radius `r`
+     * is outside when that is `< -r` on any. Cached like the matrices. An infinite far plane
+     * (`far = Infinity`) is all zeros but `d > 0`, which never rejects. Read-only.
+     */
+    get frustum(): Float32Array;
+    /**
+     * Is a world-space sphere at least partly inside the frustum? `radius` 0 tests a point. Pure
+     * plane tests; nothing allocates.
+     */
+    seesSphere(x: number, y: number, z: number, radius: number): boolean;
+    private touch2d;
+    private touch;
+    private update;
+}