@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/render/renderer.d.ts

@@ -0,0 +1,741 @@
+import { Camera } from './camera.js';
+import { type RendererCaps } from './compressed.js';
+import { type Drawable, type DrawParams, Frame, type FrameSink, type InstanceBatch, type InstanceParams } from './frame.js';
+import { FullscreenPass, type FullscreenPassDesc } from './fullscreen.js';
+import { type GpuPassTimes, GpuTimer } from './gpu-timer.js';
+import { InstanceList, type InstanceListOptions } from './instance-list.js';
+import { type MeshLod, type MeshLodChain, type MeshLodDesc } from './lod.js';
+import { Material, type MaterialDesc } from './material.js';
+import { Mesh, type MeshBounds, type MeshDesc } from './mesh.js';
+import { PingPong } from './ping-pong.js';
+import { SceneTarget, type SceneTargetAux, type SceneTargetDesc, type SceneTargetViewport } from './scene-target.js';
+import { type PixelData, type SamplerKind, Texture, type TextureDesc, type TextureLike, type TextureSource } from './texture.js';
+import { type Transform } from './transform.js';
+export interface PostInputs {
+    color: TextureLike;
+    emissive: TextureLike;
+    time: number;
+    dt: number;
+    /**
+     * The target's depth buffer when a depth camera rendered into it this frame (ws/post-depth),
+     * else `null` (the 2D path). Same size as `color`; `depth24plus`, bind it as `texture_depth_2d`.
+     */
+    depth: TextureLike | null;
+    /** The last depth camera's projection, with `depth`; `null` without it. */
+    projection: PostProjection | null;
+    /**
+     * The matrices of the last camera that rendered into the target this frame (ws/render-4):
+     * what a reprojecting pass (TAA, motion blur) needs. `null` before any view.
+     */
+    view: PostView | null;
+    /** The target's `rg8unorm` roughness/metalness attachment (`SceneTargetDesc.aux`), else null. */
+    roughMetal: TextureLike | null;
+    /** The target's `rg16float` screen-space velocity attachment (`SceneTargetDesc.aux`), else null. */
+    velocity: TextureLike | null;
+}
+/** A view's matrices for post passes: this frame's (with jitter) and last frame's (without). */
+export interface PostView {
+    viewProj: Float32Array;
+    invViewProj: Float32Array;
+    previousViewProj: Float32Array;
+    previousView: Float32Array;
+    /** The sub-pixel jitter applied this frame, in target pixels; `[0, 0]` without. */
+    jitter: [number, number];
+}
+/** A frame's projection for depth-reading post passes: clip planes and the column-major matrix. */
+export interface PostProjection {
+    near: number;
+    /** `Infinity` for an infinite far plane. */
+    far: number;
+    proj: Float32Array;
+}
+/**
+ * The final stage: turns the HDR scene into swapchain pixels. See `@thunderclap-engine/engine/post`.
+ * `viewport` (ws/xr-post) asks for the result in that part of `output` only (texture px, so an
+ * eye of a shared XR layer), loading the rest; without it the whole output is written. The
+ * inputs may be smaller or larger than the last `resize`: a processor sizes itself to them.
+ */
+export interface PostProcessor {
+    /**
+     * The processor reads `PostInputs.view.jitter` and reprojects (TAA): the renderer then applies
+     * each camera's `setJitter` offset to its projection. Without it no camera is ever jittered,
+     * whatever `setJitter` was given, so existing pages never move.
+     */
+    wantsJitter?: boolean;
+    resize(width: number, height: number): void;
+    encode(encoder: GPUCommandEncoder, inputs: PostInputs, output: GPUTextureView, viewport?: SceneTargetViewport): void;
+}
+/** Arguments to `Renderer.createSpriteMaterial`. */
+export interface SpriteMaterialOptions {
+    /** The sprite texture (an atlas, a `Texture`, `defaultTextures(device).white`). */
+    texture: TextureLike;
+    /** Debug label. Default `'sprite'`. */
+    label?: string;
+    /** Default `'alpha'`. */
+    blend?: MaterialDesc['blend'];
+    /** Default `'linear-clamp'`; pixel art wants `'nearest-clamp'`. */
+    sampler?: SamplerKind;
+}
+export interface RendererOptions {
+    logicalWidth?: number;
+    logicalHeight?: number;
+    /** Initial instance capacity (grows by doubling). Default 4096. */
+    initialInstances?: number;
+    /** Aux attachments of the default `target` (`SceneTargetDesc.aux`); none by default. */
+    aux?: SceneTargetAux;
+}
+export interface RendererGpu {
+    device: GPUDevice;
+    context: GPUCanvasContext;
+    format: GPUTextureFormat;
+}
+export interface RenderStats {
+    drawCalls: number;
+    /**
+     * Triangles the scene passes asked the GPU for, summed over views: each draw's indices (or
+     * vertices, non-indexed) / 3 × its instance count. Drawables and the shadow pass are not
+     * counted (a drawable issues its own draws).
+     */
+    triangles: number;
+    /** Instances the scene passes drew (`frame.mesh` / `sprite` draws and batch instances), summed over views. */
+    instances: number;
+    drawables: number;
+    /** Batches (`frame.meshes`) and lists (`frame.list`) the scene passes drew, summed over views. */
+    batches: number;
+    /** Mesh draws skipped by frustum culling (`camera.cull`), summed over the frame's views. */
+    culled: number;
+    /**
+     * Instances drawn into the sun's shadow map, summed over the frame's views: the opaque
+     * casters inside the sun's box, whether or not the view's frustum sees them.
+     */
+    shadowDraws: number;
+    /**
+     * Scene render passes encoded this frame: one per view, two for a view that split at the
+     * opaque/blended boundary for a `readsDepth` drawable (ws/render-hooks). Shadow and post
+     * passes are not counted.
+     */
+    passes: number;
+    /**
+     * Instances drawn per LOD level (`frame.mesh` with a `MeshLod`, ws/render-5), summed over the
+     * scene passes of the frame: `lodCounts[i]` drew level `i`. Grows to the longest chain drawn;
+     * zeroed by `beginFrame`.
+     */
+    lodCounts: number[];
+}
+/** Options of `Renderer.textureFromSource`. */
+export interface TextureFromSourceOptions {
+    /** Store the bytes as `rgba8unorm` (no sRGB decode) for data maps. Default false (sRGB colour). */
+    linear?: boolean;
+    /** Allocate and fill the full mip chain. Default false (one level). */
+    mips?: boolean;
+    /** Texture label when the options object replaces the label argument. Default `'image'`. */
+    label?: string;
+}
+/**
+ * Internal resolution of the scene targets relative to the output (the canvas backbuffer).
+ * The post stack (or the built-in present pass) upscales to the full output, so DOM UI and
+ * the final composite stay at native resolution.
+ */
+export interface ResolutionOptions {
+    /** Linear scale of the scene targets vs the output, 0.25..1. Default 1. */
+    scale?: number;
+    /** Cap on scene-target pixels (width × height). Default unlimited. */
+    maxPixels?: number;
+}
+/**
+ * Frame timing, filled in when `Renderer.timingEvery > 0`.
+ *
+ * With `timestamp-query` (`source: 'timestamp'`), `gpuMs` is the GPU time from the frame's
+ * first pass to its last, and `passes` splits it by pass label (`pre`, `scene`, plus whatever
+ * the post processor labels, e.g. `bloom`, `rays`, `composite`).
+ *
+ * Without it (`source: 'queue'`), `gpuMs` is the time from submit to
+ * `queue.onSubmittedWorkDone()`. With vsync the queue is normally idle at submit, so this
+ * approximates the GPU cost of the frame; when the GPU falls behind it also includes
+ * queueing, which still reads as "over budget". `passes` stays empty.
+ */
+export interface FrameTiming {
+    /** Last GPU sample (ms). */
+    gpuMs: number;
+    /** Where `gpuMs` comes from. */
+    source: 'timestamp' | 'queue';
+    /** Per-pass GPU ms of the last timestamp sample (empty on `queue`). */
+    passes: GpuPassTimes;
+    /** CPU time of the last frame, `beginFrame` → `endFrame` returning (ms). */
+    cpuMs: number;
+    /** GPU samples taken so far. */
+    samples: number;
+    /**
+     * Resolves once the first GPU sample has landed (`samples` > 0; immediately when one already
+     * has), so a bench or demo can wait for a real `gpuMs` instead of polling. Set `timingEvery`
+     * before (or right after) calling it: with timing off, no sample is ever taken. Resolves at
+     * once when GPU timing is unsupported (a device with neither `timestamp-query` nor
+     * `queue.onSubmittedWorkDone`) or the renderer is destroyed before a sample arrives.
+     */
+    ready(): Promise<void>;
+}
+/** Smallest scale `setResolution` accepts (a quarter of the output in each direction). */
+export declare const MIN_RESOLUTION_SCALE = 0.25;
+/**
+ * Effective scene-target size for an output size and resolution options. Pure (unit-tested).
+ * Sizes are rounded to even numbers so the half-res bloom/ray targets stay pixel aligned.
+ */
+export declare function sceneSize(outW: number, outH: number, opts: Required<ResolutionOptions>): {
+    width: number;
+    height: number;
+    scale: number;
+};
+/** The per-frame jitter hook of `Renderer.setJitter`: pixels `[x, y]` for frame `frame`. */
+export type JitterFn = (frame: number) => readonly [number, number];
+/**
+ * WebGPU renderer: owns the HDR scene targets, instanced batch, materials and the hand-off to
+ * the post stack. One per canvas.
+ *
+ * ```ts
+ * const r = new Renderer(gpu);
+ * r.resize(w, h);
+ * const f = r.beginFrame(time, dt);
+ * f.sprite(myMaterial, { x: 960, y: 540, w: 200, h: 200 });
+ * r.endFrame();                      // = r.render(f, r.camera) into r.target, then post + present
+ * ```
+ *
+ * A frame is `beginFrame` → record → `render(frame, camera, target?, viewport?)` any number of
+ * times → `endFrame`. Each `render` runs the recorded draw lists through one camera (its layer
+ * mask, sort and depth) into a `SceneTarget` (default `renderer.target`, what the surface
+ * shows); `endFrame` renders through `renderer.camera` when nothing called `render`, then runs
+ * the post stack (or the built-in present) from `renderer.target` to the swapchain and submits.
+ */
+export declare class Renderer implements FrameSink {
+    readonly device: GPUDevice;
+    readonly context: GPUCanvasContext;
+    /** Swapchain format. */
+    readonly format: GPUTextureFormat;
+    /**
+     * Formats of the scene pass's two base colour targets (HDR colour, HDR emissive). A target
+     * with aux attachments adds more after them: build a pipeline's target list with
+     * `sceneTargets`, not from this.
+     */
+    readonly sceneFormats: readonly GPUTextureFormat[];
+    readonly logicalWidth: number;
+    readonly logicalHeight: number;
+    /**
+     * The camera the scene pass draws through, uploaded to the camera block each frame.
+     * Default `Camera.ortho2d(logicalWidth, logicalHeight)`; its `x`, `y`, `zoom` and
+     * `rotation` pan the 2D view. Assign another `Camera` to swap presets.
+     */
+    camera: Camera;
+    readonly samplers: Record<SamplerKind, GPUSampler>;
+    /**
+     * What the device can do beyond core WebGPU, read from its features at construction
+     * (ws/render-5): `caps.compressed.bc` / `.etc2` / `.astc` are the block-compression families
+     * `uploadKtx2` can upload. A device gets them only when created with them
+     * (`compressionFeatures(adapter)` in `requiredFeatures`).
+     */
+    readonly caps: RendererCaps;
+    readonly globalsLayout: GPUBindGroupLayout;
+    /**
+     * The engine uniforms of the frame's first view (`@group(0)`: globals, camera and lights
+     * blocks, the sun's shadow map and its sampler). Replaced when the shadow map is (re)created.
+     */
+    globalsBindGroup: GPUBindGroup;
+    readonly quad: Mesh;
+    /** Built-in sprite material bound to the default white texture (solid colour quads via tint). */
+    readonly defaultSprite: Material;
+    readonly stats: RenderStats;
+    /**
+     * The band around each LOD threshold an instance must cross before it changes level, as a
+     * fraction of the threshold (default 0.1): see `pickLodLevel`. 0 turns it off.
+     */
+    lodHysteresis: number;
+    /** See `FrameTiming`. Only updated while `timingEvery > 0`. */
+    readonly timing: FrameTiming;
+    /** Resolvers of `timing.ready()` promises waiting on the first GPU sample. */
+    private readonly readyWaiters;
+    /**
+     * Pass timer when the device has `timestamp-query`, else null. Passes encoded during
+     * `endFrame` (the post processor's included) label themselves with `gpuTimer.pass(label)`;
+     * it returns undefined except on sampled frames.
+     */
+    readonly gpuTimer: GpuTimer | null;
+    /**
+     * Sample GPU time every N frames (0 = off). One sample is in flight at a time; each costs one
+     * `onSubmittedWorkDone` promise.
+     */
+    timingEvery: number;
+    /** Final stage. Defaults to a plain tonemap + sRGB present; set to a `PostStack`. */
+    post: PostProcessor | null;
+    /** Scene-target size (internal resolution). The post stack reads these. */
+    width: number;
+    height: number;
+    /** Output (canvas backbuffer) size, as passed to `resize`. */
+    outputWidth: number;
+    outputHeight: number;
+    /**
+     * The default `SceneTarget`, at the scene resolution: what `render` draws into unless given
+     * another, what the post stack reads and what the surface shows.
+     */
+    readonly target: SceneTarget;
+    private readonly views;
+    private viewCount;
+    /** The sun's shadow map and its pipelines (see `shadow.ts`). */
+    private readonly shadow;
+    /** Engine uniform slots for the shadow passes of a frame (the sun camera in the camera block). */
+    private readonly shadowSlots;
+    private shadowCount;
+    private readonly shadowRect;
+    private readonly globalsData;
+    private readonly globalsU32;
+    private readonly viewRect;
+    /** Targets rendered into so far this frame, and whether their depth was cleared. */
+    private readonly usedTargets;
+    private readonly usedDepth;
+    /** The last depth camera into each used target (ws/post-depth: `PostInputs.projection`). */
+    private readonly usedCamera;
+    /** `sceneTargets` lists per blend state object (`NO_BLEND` for none; weak, so a caller's
+     * fresh blend object is not kept), indexed by aux key. */
+    private readonly sceneTargetLists;
+    /** The target `buildDraws` is building for (its aux set keys the pipelines). */
+    private drawTarget;
+    private readonly postProjection;
+    /** `PostInputs.view` storage, one per inputs object (`postInputs`, `resolveInputs`). */
+    private readonly postView;
+    private readonly resolveView;
+    private usedCount;
+    private instanceData;
+    private instanceBuffer;
+    /** Byte offset in `instanceBuffer` where the next view's instances go. */
+    private instanceBase;
+    /** Instance buffers outgrown this frame, destroyed after submit (passes still reference them). */
+    private readonly retired;
+    /**
+     * The shared previous-matrix lane (ws/render-7): 12 floats per instance, indexed like the
+     * view's upload, for batches with `prevMatrices` drawn into a velocity target by an aux
+     * material. Made on first use; `laneBase` is the current view's byte offset in it.
+     */
+    private laneData;
+    private laneBuffer;
+    private laneBase;
+    /** The previous matrices `copyBatch` / `copyBatchLod` copy into `laneData`, else null. */
+    private laneSrc;
+    /** Batch records with `prev` this frame, and whether the current view drew one with the lane. */
+    private laneRecs;
+    private laneUsed;
+    private instanceCount;
+    /** Instances in this frame's batches (`pushBatch`), excluding lists; they take the sort path. */
+    private batchInstances;
+    /** Batch records this frame (lists included). */
+    private batchRecs;
+    /** Records with a LOD chain this frame. */
+    private lodRecs;
+    /** The camera `pickLods` is picking for. */
+    private lodCam;
+    /** The LOD level memory of each camera (view) that drew a LOD record. */
+    private readonly lodMemory;
+    /** Per camera: each single draw's Transform history for the velocity lane (ws/render-8). */
+    private readonly motionMemory;
+    /** Per-instance level scratch of `copyBatchLod` (-1: culled). */
+    private lodScratch;
+    /** `copyBatchLod`'s buckets: first instance, count and write cursor per level. */
+    private bucketFirst;
+    private bucketCount;
+    private bucketAt;
+    /** `setJitter`'s hook, the frames it has run and this frame's offset. */
+    private jitterFn;
+    private jitterFrame;
+    private jitterX;
+    private jitterY;
+    /** Cameras the hook has jittered (cleared when it is removed). */
+    private readonly jitterCams;
+    /** Batch or list draws of the current view's scene pass, and instances `copyBatch` dropped. */
+    private sceneBatches;
+    private batchCulled;
+    /** Instances of the lists the current view's scene pass draws (not in the upload). */
+    private sceneListInstances;
+    /** This view's scene commands (`buildDraws`). */
+    private readonly scene;
+    /** This view's shadow-pass commands (`buildShadowDraws`): opaque casters inside the sun box. */
+    private readonly shadowCmds;
+    private readonly recs;
+    private recCount;
+    /** True while every draw this frame had `order` >= the previous draw's. */
+    private ordered;
+    private lastOrder;
+    private sortIdx;
+    private sortTmp;
+    private sortDepth;
+    /** Record indices of the shadow list, sorted by mesh then material (`sortShadow`). */
+    private shadowIdx;
+    private shadowTmp;
+    /** True while `sortDraws` orders the shadow list (mesh, material, index) instead of the scene. */
+    private sortShadow;
+    /** Stable numeric keys for meshes and materials, for the shadow sort; grows per new object. */
+    private readonly keys;
+    private nextKey;
+    /** Instance data in draw order, used when sorting or layer culling reorders draws. */
+    private sortedData;
+    /** The array `endFrame` uploads: `instanceData` (submission order) or `sortedData`. */
+    private uploadData;
+    /** Instances `render` uploads for this view: the scene's, then the shadow list's copies. */
+    private uploadCount;
+    /** Instances the scene pass draws this view (layer- and frustum-culled draws excluded). */
+    private sceneCount;
+    /** Draws the last `buildDraws` dropped by the frustum test. */
+    private culledCount;
+    private readonly prePasses;
+    private readonly prepared;
+    /**
+     * Where the last `buildDraws` would split the scene commands for a `readsDepth` drawable:
+     * the index of the first blended command at or above the lowest hooked order; -1 when no
+     * visible drawable asked (or the camera has no depth test).
+     */
+    private splitAt;
+    /** Drawables whose `afterOpaque` ran for the current view (once each). */
+    private readonly hooked;
+    /** The `ViewInfo` handed to `afterOpaque`, reused across views. */
+    private readonly viewInfo;
+    /** Per-draw uniform sets with blocks staged this frame. */
+    private readonly drawUniformSets;
+    private readonly dynamicOffsets;
+    private readonly frame;
+    private readonly present;
+    private presentGroup;
+    private readonly postInputs;
+    /** `resolve` (ws/xr-post): inputs for an explicit target and the present group cached for it. */
+    private readonly resolveInputs;
+    private resolveTarget;
+    private resolveColor;
+    private resolveGroup;
+    /** The frame's command encoder, opened by the first `render`, submitted by `endFrame`. */
+    private encoder;
+    private sampled;
+    private readonly resizeListeners;
+    private readonly resolution;
+    private inFrame;
+    private destroyed;
+    private frameStart;
+    private timingFrame;
+    private timingPending;
+    private timingSubmit;
+    private readonly timingListeners;
+    private readonly onTimingDone;
+    private readonly onTimerResult;
+    constructor(gpu: RendererGpu, opts?: RendererOptions);
+    /** The default target's HDR colour texture (`target.color`). */
+    get sceneColor(): Texture;
+    /** The default target's HDR emissive texture (`target.emissive`). */
+    get sceneEmissive(): Texture;
+    /**
+     * Set the output size (canvas backbuffer pixels). The HDR scene targets follow it, scaled
+     * by `setResolution`. Cheap no-op when nothing changes.
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Render the scene below output resolution: `scale` (0.25..1, linear) and/or a `maxPixels`
+     * budget. The final pass upscales to the canvas. Only the given fields change. Changing it
+     * reallocates the scene and post targets, so do it rarely (a resolution controller should
+     * step, not track every frame).
+     */
+    setResolution(opts: ResolutionOptions): void;
+    /** Current resolution settings (scale as requested, before the pixel budget). */
+    get resolutionOptions(): Readonly<Required<ResolutionOptions>>;
+    /** Effective linear scale of the scene targets vs the output (after the pixel budget). */
+    get resolutionScale(): number;
+    private applyResolution;
+    /** Called with every GPU time sample (see `timingEvery`). Returns unsubscribe. */
+    onGpuTime(fn: (gpuMs: number) => void): () => void;
+    /** Called after the scene targets change size, with the scene size. Returns unsubscribe. */
+    onResize(fn: (width: number, height: number) => void): () => void;
+    /**
+     * The colour target list (`GPUFragmentState.targets`) of a pipeline that draws into the
+     * scene pass of a target with aux key `aux` (`SceneTarget.auxKey`; default
+     * `renderer.target`'s, ws/render-10): colour and emissive (`sceneFormats`) with `blend`,
+     * then each aux attachment the target has (rough-metal, velocity) with `writeMask: 0`. Every
+     * pipeline drawing into the scene pass takes its targets from here (materials build theirs
+     * the same way), so its count matches the pass's whichever aux attachments are on. A
+     * `Drawable` that may draw into more than one target keys its pipelines on
+     * `frame.auxKey` (set per view, like `frame.depthFormat`) and passes it here. The list is
+     * built once per (`blend`, `aux`) and the same array returned after; do not mutate it.
+     */
+    sceneTargets(blend?: GPUBlendState, aux?: number): GPUColorTargetState[];
+    createMaterial(desc: MaterialDesc): Material;
+    /**
+     * The built-in textured sprite material (`texture × vertex colour × tint`; emissive is the
+     * colour × `emissive`): `createSpriteMaterial({ texture, label, blend, sampler })`, the same
+     * option-object shape as `createMaterial`. `label` defaults to `'sprite'`, `blend` to
+     * `'alpha'` and `sampler` to `'linear-clamp'`.
+     */
+    createSpriteMaterial(opts: SpriteMaterialOptions): Material;
+    createMesh(desc: MeshDesc): Mesh;
+    /**
+     * Upload a LOD chain (ws/api-render): one mesh per `geometries` entry, labelled
+     * `<label>-lod<i>`, returned with the thresholds and the geometries as a `MeshLod` that
+     * `frame.mesh` takes in place of a mesh. geom's `createLodChain(g, ratios)` builds the
+     * geometries (level 0 is `g`, so `ratios.length + 1` levels and `ratios.length` thresholds).
+     * Throws on an empty chain or more thresholds than levels.
+     */
+    createMeshLod(desc: MeshLodDesc): MeshLodChain;
+    createTexture(desc: TextureDesc): Texture;
+    /**
+     * A scene target of its own size for `render` to draw a view into offscreen (a portal, a
+     * minimap, a picture-in-picture camera). Its `color`/`emissive` are sampleable textures;
+     * it is not resized with the surface. The caller destroys it.
+     */
+    createSceneTarget(desc: SceneTargetDesc): SceneTarget;
+    /** Offscreen render target (sampleable). Default format is the HDR scene format. */
+    createRenderTarget(desc: TextureDesc): Texture;
+    createFullscreenPass(desc: FullscreenPassDesc): FullscreenPass;
+    /**
+     * Upload an image/canvas/ImageData. By default it is an sRGB colour texture (sampled as
+     * linear). Pass `{ linear: true }` for data (masks, normals, lookup tables): the bytes are
+     * stored as `rgba8unorm` and sampled exactly as written, with no sRGB decode. `{ mips: true }`
+     * allocates the full mip chain and fills it on the GPU (`generateMipmaps`), the same as
+     * `loadTexture`; the default is one level. The options object may replace the label
+     * (`textureFromSource(src, { mips: true })`), or follow it.
+     */
+    textureFromSource(source: TextureSource, label?: string | TextureFromSourceOptions, opts?: TextureFromSourceOptions): Texture;
+    /**
+     * Upload raw texels. Default format `rgba8unorm` (linear data, no sRGB decode); any format
+     * from `bytesPerTexel` works, e.g. `r8unorm` masks or `rgba32float` lookup tables. `data`
+     * holds `width × height` tightly packed texels.
+     */
+    textureFromPixels(desc: {
+        width: number;
+        height: number;
+        data: PixelData;
+        format?: GPUTextureFormat;
+        label?: string;
+        usage?: GPUTextureUsageFlags;
+    }): Texture;
+    /** Overwrite a whole texture with tightly packed texels (e.g. a CPU-updated data texture). */
+    writePixels(tex: Texture, data: PixelData): void;
+    /**
+     * Two render targets for feedback passes (see `PingPong`). Default format is the HDR
+     * scene format.
+     */
+    createPingPong(desc: TextureDesc): PingPong;
+    /**
+     * Generate a texture procedurally on the GPU. `wgsl` must define
+     * `fn shade(uv: vec2f) -> vec4f` returning **linear** colour (uv 0..1, top-left origin).
+     * Engine noise helpers (`engine_fbm` …) are available. Optional uniforms at
+     * `@group(0) @binding(0)`.
+     */
+    textureFromShader(opts: {
+        width: number;
+        height: number;
+        wgsl: string;
+        label?: string;
+        format?: GPUTextureFormat;
+        uniforms?: Float32Array<ArrayBuffer>;
+    }): Texture;
+    /**
+     * The renderer's jitter hook (ws/render-6): `fn(frame)` runs once per `beginFrame` (`frame`
+     * counts from 0 since the hook was set) and its `[x, y]` (target pixels, +x right, +y down)
+     * goes to every camera `render` draws this frame, XR eyes included, through
+     * `camera.setJitter`, with the jitter target set per view as when the post processor
+     * `wantsJitter`. The renderer keeps each camera's history (`recordHistory`), so
+     * `previousViewProj` and `previousView` stay unjittered. `null` removes the hook and clears
+     * the jitter of every camera it reached. Without a hook `Camera.setJitter` works as before.
+     * Return a reused tuple to keep the frame allocation-free.
+     */
+    setJitter(fn: JitterFn | null): void;
+    /**
+     * The jitter hook installed by `setJitter`, or null when none is (ws/render-8). Read-only:
+     * compare it by identity, so a post stack can check whether the renderer still holds the
+     * hook it installed (`renderer.jitter === myHook`) before clearing it, and leave another
+     * owner's hook alone.
+     */
+    get jitter(): JitterFn | null;
+    /**
+     * The LOD level instance `index` of a LOD batch or list (`frame.meshes` / `frame.list` on a
+     * `MeshLod`) drew at for `camera` (default `this.camera`) in the last frame that drew it,
+     * or -1 when it has none (ws/render-7). For probes and debug overlays: it reads the view's
+     * level memory, which a keyed `InstanceList` carries by key across flushes.
+     */
+    lodLevelOf(batch: object, index: number, camera?: Camera): number;
+    /** Start recording a frame. `time`/`dt` in seconds are exposed to shaders via `globals`. */
+    beginFrame(time: number, dt: number): Frame;
+    /**
+     * Run the draw lists recorded in `frame` through `camera` into `target` (default: the
+     * renderer's own, which the surface shows). Call it any number of times between
+     * `beginFrame` and `endFrame`; `endFrame` calls it with `renderer.camera` when nothing did.
+     *
+     * Each call is one scene pass: the camera's layer mask culls, its depth flags pick the sort
+     * and the depth attachment, and its `screen` rect is the viewport. A `screen` in logical
+     * units (the `ortho2d` default is the whole design space) maps onto the target in
+     * proportion; one inside the unit square (the perspective default `0,0,1,1`) is a fraction
+     * of it. The first view into a target this frame clears it (`frame.clearColor`); later ones
+     * draw over it, so a UI camera over a world camera or two half-screen cameras just work.
+     * The first call opens the frame's command encoder and runs the pre-passes and drawable
+     * `prepare` hooks (once per frame). No allocation in steady state.
+     */
+    render(frame: Frame, camera: Camera, target?: SceneTarget): void;
+    /** Viewport and scissor of a view that does not cover its target. */
+    private setViewRect;
+    /**
+     * Encode scene commands `[from, to)` into `pass` (group 0 already bound to `slot.group`),
+     * counting draw calls and drawables into `stats`.
+     */
+    private encodeDraws;
+    /**
+     * Run the post stack (or the built-in present) from `target` into `out` now, inside the frame
+     * (ws/xr-post): what `endFrame` does from `renderer.target` to the swapchain, for any target
+     * and any output. `viewport` confines the result to that part of `out` (texture px) and loads
+     * the rest, so two eyes resolve into one XR layer texture one after the other. The target is
+     * consumed: the next `render` into it this frame clears it again, so one HDR target serves
+     * every eye in turn. Needs a `render` before it this frame (the encoder is open then).
+     */
+    resolve(target: SceneTarget, out: GPUTextureView, viewport?: SceneTargetViewport): void;
+    /**
+     * `PostInputs.depth` / `projection` (ws/post-depth): the target's depth and the last depth
+     * camera's projection when one rendered into it this frame, else `null`. No allocation.
+     */
+    private fillDepthInputs;
+    /**
+     * Finish the frame: `render(frame, renderer.camera)` when nothing rendered yet, then the
+     * post stack (or the built-in present) from `renderer.target` to the swapchain, and submit.
+     * `{ present: false }` skips the post stack and the swapchain (no `getCurrentTexture`): the
+     * frame's views went to their own targets, as an XR session's eyes do (ws/xr), resolved into
+     * the layer with `resolve` (ws/xr-post).
+     */
+    endFrame(opts?: {
+        present?: boolean;
+    }): void;
+    /** Every `timingEvery` frames, when no sample is in flight. */
+    private wantSample;
+    private emitGpuTime;
+    /** `timing.ready()`: a settled promise once a sample exists, else one kept until the first. */
+    private timingReady;
+    private resolveReady;
+    destroy(): void;
+    pushInstance(material: Material, mesh: Mesh, tr: Transform | null, p: DrawParams | InstanceParams, bounds: MeshBounds | null, lod?: MeshLod | null): void;
+    pushBatch(material: Material, mesh: Mesh, batch: InstanceBatch, bounds: MeshBounds | null, list: InstanceList | null, lod?: MeshLod | null): void;
+    /**
+     * A retained `InstanceList` of up to `capacity` instances of `mesh` with `material`, drawn
+     * with `frame.list(list)`. Owns a GPU buffer; `list.destroy()` releases it. A `MeshLod`
+     * (ws/render-6) makes a list whose instances pick their level per view.
+     */
+    createInstanceList(mesh: Mesh | MeshLod, material: Material, capacity: number, opts?: InstanceListOptions): InstanceList;
+    pushDrawable(d: Drawable, order: number, layers: number): void;
+    pushPrePass(fn: (encoder: GPUCommandEncoder) => void): void;
+    private nextRec;
+    /**
+     * Turn this frame's draw records into batched commands. Draws whose `layers` miss the
+     * camera's mask are dropped; with `camera.cull`, so are mesh draws whose world bounding
+     * sphere lies outside any plane of `camera.frustum` (counted in `culledCount`). Without
+     * depth or culling, draws sort by `order` then submission index; when every `order` is
+     * already non-decreasing (the default) nothing moves and the instance data uploads as
+     * recorded. With `camera.depthTest`, the keys are `order`, then opaque before blended, then
+     * depth (opaque front-to-back, blended back-to-front), then submission index. Sets
+     * `uploadData` / `uploadCount`; returns whether depth is on. With `frame.lights.sun.shadow`
+     * set, `buildShadowDraws` then appends the shadow list's instances to the same upload.
+     */
+    private buildDraws;
+    /** `cam`'s motion memory, advanced to a new view (one per `render` with lane records). */
+    private motionView;
+    /**
+     * Write the previous world matrix of a single draw's `tr` into lane slot `slot`: the matrix
+     * `tr` held at this view's last frame, or the current one (zero motion) when the view did
+     * not draw it then (first seen, or culled or skipped last frame). The current matrix is
+     * `src[from..from+12]`, as recorded. A transform drawn twice with different matrices in one
+     * view is a scratch transform: it reports no motion of its own from then on. Allocates only
+     * on a transform's first draw in a view.
+     */
+    private writeMotion;
+    /**
+     * Pick this view's level of every LOD record (`frame.mesh` with a `MeshLod`): the projected
+     * height of its world sphere through `cam` on the view's viewport (`lodSizePx`) times
+     * `cam.lodBias`, against the chain's thresholds with `lodHysteresis` around the level its key
+     * drew last (`pickLodLevel`). Sets the record's `mesh` (so the scene and shadow lists draw the
+     * level) and, for opaque materials, the sort keys that group a level's instances into one
+     * draw. No allocation.
+     */
+    private pickLods;
+    /**
+     * `pickLods` for a batch or list record: every instance's level for this view, from the
+     * sphere of `meshes[0].bounds` through its matrix (as `pushInstance` places it), with the
+     * hysteresis held per instance index in the view's memory for the batch. The levels land in
+     * `r.lodLevels` (that memory), read by the scene and the shadow copy alike, so a shadow pass
+     * draws the level the view picked. Grows the memory only when the batch does.
+     */
+    private pickBatchLods;
+    /** Count `n` scene instances of LOD level `level` in `stats.lodCounts`. */
+    private countLod;
+    /**
+     * Copy the instances of batch record `r` into `dst` from instance `inst` on, in the instance
+     * format (matrices, then `params` or the defaults with the matrix columns' lengths as size).
+     * With `planes` and a batch without bounds (`r.mb` set), each instance is tested the way
+     * `pushInstance` places a mesh sphere and the ones outside are skipped, counted in
+     * `batchCulled`. Returns the instances written. No allocation.
+     */
+    private copyBatch;
+    /**
+     * `copyBatch` for a LOD batch or list: the instances that pass the same per-instance test,
+     * written bucketed by the level `pickLods` chose for this view (`r.lodLevels`), level 0
+     * first. Sets `bucketFirst` / `bucketCount` per level and `batchCulled`; returns the
+     * instances written. Grows its scratch only when a batch outgrows it.
+     */
+    private copyBatchLod;
+    /** The shadow pipeline of a caster record (its current `mesh`). */
+    private shadowPipeline;
+    /**
+     * Build this view's shadow-pass commands: every opaque mesh draw with `castShadow` on the
+     * camera's layers whose bounding sphere touches the sun's box (`ShadowMap.sunCamera.frustum`,
+     * placed by `render` before the lists are built), whether or not the view's own frustum sees
+     * it. The casters are sorted by mesh, then material, then submission index, their instance
+     * data copied into `dst` from `inst` on (after the scene's), and batched into `shadowCmds`
+     * with the scene's keys, so one `(mesh, material)` is one instanced draw. Returns the new
+     * instance count of the upload. No allocation in steady state.
+     */
+    private buildShadowDraws;
+    /** A stable small integer for a mesh or material (assigned on first sight). */
+    private keyOf;
+    /** The scene pipeline of a mesh record for `depth` into the view's target. */
+    private scenePipeline;
+    /**
+     * Append a record to `list` as a command drawn with `pipeline`, merging into the previous
+     * one when it continues it (same pipeline, material, mesh, offset and shadow flag, and its
+     * instances follow on). Drawables pass `pipeline` null.
+     */
+    private batch;
+    /**
+     * True when record `a` draws before record `b` (a total order: ties go by index). For the
+     * scene list: `order`, then (with depth) group and depth; for the shadow list
+     * (`sortShadow`): mesh key, then material key.
+     */
+    private drawsBefore;
+    /** Bottom-up merge sort of `idx[0..n)` with `drawsBefore`, `tmp` as scratch; no allocation. */
+    private sortDraws;
+    private nextCmd;
+    private growInstances;
+    /**
+     * Upload this view's scene instances of the shared previous-matrix lane at the byte offset
+     * matching `base` in the instance buffer (48 bytes per instance where it has 112), growing
+     * the lane buffer when the frame outgrows it (the old one retires after submit).
+     */
+    private uploadLane;
+    private makeInstanceBuffer;
+    /**
+     * The engine uniform slot for view `i` of a frame, made on first use (slot 0 at startup).
+     * Its bind group carries the sun's shadow map at binding 3 (the 1×1 placeholder until a
+     * shadow pass has rendered; `encodeShadow` rebuilds the groups when the map changes).
+     */
+    private viewSlot;
+    /** The uniform slot for shadow pass `i` of a frame; binds the placeholder, not the map. */
+    private shadowSlot;
+    /** A `globalsLayout` bind group over `buffer`, with the shadow map (or its placeholder) at 3. */
+    private globalsGroup;
+    /**
+     * When `frame.lights.sun.shadow` is set and this view has opaque shadow casters inside the
+     * sun's box, encode one depth-only pass into the sun's shadow map (through
+     * `ShadowMap.sunCamera`, an ortho box centred on `camera.position`, placed by `render`) over
+     * `shadowCmds` (built by `buildShadowDraws`: casters the view frustum culled included), before
+     * its scene pass. Returns what `writeView` puts in the lights block, or null when no shadow
+     * was rendered.
+     */
+    private encodeShadow;
+    /**
+     * Upload the globals, camera and lighting blocks of one view (`viewRect` holds its viewport;
+     * `view_index` is `camera.viewIndex`; `shadow` is this view's shadow pass, if any).
+     */
+    private writeView;
+}