@yali-engine/render 0.0.0-stage → 0.4.0

package/dist/render-plugin.d.ts

@@ -0,0 +1,239 @@
+import { type Component, type YaliPlugin } from '@yali-engine/core';
+import { OrbitCamera } from './camera.ts';
+import { DebugLines } from './debug-lines.ts';
+import { type Gpu } from './device.ts';
+import { MaterialStore, MeshStore } from './meshes.ts';
+import { type DeviceFilterRule, type DeviceProfile, type Tier } from './device-profile.ts';
+import { FrameGraph } from './frame-graph.ts';
+import { GpuHealth } from './gpu-health.ts';
+import { GpuTimer } from './gpu-timer.ts';
+import { PipelineCache } from './pipeline-cache.ts';
+import { type SkyOptions } from './environment.ts';
+import { type ShadowOptions } from './shadows.ts';
+import { type LightingOptions, type SceneControls } from './scene.ts';
+import { type TextureFamily, TextureStore } from './textures.ts';
+import { type ToneCurve } from './tonemap.ts';
+import { type PostControls, type PostOptions } from './post-options.ts';
+import { Viewport, type ViewportOptions } from './viewport.ts';
+/** The tone-mapping knobs: `exposure` and `curve` may change any frame. */
+export interface ToneControls {
+    exposure: number;
+    curve: ToneCurve;
+}
+/** The environment lighting: a procedural sky (`setSky` rebuilds the cube and SH). */
+export interface EnvironmentControls {
+    setSky(sky: SkyOptions): void;
+    readonly sky: Readonly<Required<SkyOptions>>;
+}
+/** The sun's shadows: `distance` may change at run time. */
+export interface ShadowControls {
+    readonly enabled: boolean;
+    readonly cascades: number;
+    readonly size: number;
+    distance: number;
+}
+/** Which backend draws (ADR-0070). */
+export type RenderBackend = 'webgpu' | 'webgpu-compat' | 'webgl2';
+/** What `@yali-engine/render` provides to other plugins (as the `render` resource). Fields are
+ *  swapped in place on device recovery, so read them each frame rather than caching. */
+export interface RenderContext {
+    /** WebGPU (core or compatibility mode), or the WebGL2 fallback where there is no WebGPU (ADR-0070). */
+    readonly backend: RenderBackend;
+    /** The WebGPU device and canvas context (replaced on recovery); null on WebGL2. */
+    gpu: Gpu | null;
+    /** The scene renderer's knobs and counters (replaced on recovery). */
+    scene: SceneControls;
+    /** The tone-mapping pass (replaced on recovery). */
+    tonemap: ToneControls;
+    /** The post-processing chain's knobs (ADR-0092): bloom, grading, TAA, FXAA. */
+    readonly post: PostControls;
+    /** The environment lighting (procedural sky, `setSky`); replaced on recovery. */
+    environment: EnvironmentControls;
+    /** Clustered point and spot lights (ADR-0067): `count`, `dropped`; replaced on recovery. */
+    lights: {
+        readonly count: number;
+        readonly dropped: number;
+    };
+    /** The sun's cascaded shadow maps (ADR-0068); replaced on recovery. */
+    shadows: ShadowControls;
+    /** The `render.Light` component (point / spot lights at their `GlobalTransform`), or null without a world. */
+    readonly Light: Component | null;
+    /** The frame graph (WebGPU; null on WebGL2, whose frame is fixed). */
+    graph: FrameGraph | null;
+    /** GPU pass timing (WebGPU; null on WebGL2). */
+    timer: GpuTimer | null;
+    /** Shared pipelines for this device (WebGPU, rebuilt on recovery; null on WebGL2). */
+    pipelines: PipelineCache | null;
+    /** Render-target sizing; `viewport.renderScale` is the dynamic-resolution knob. */
+    readonly viewport: Viewport;
+    readonly camera: OrbitCamera;
+    /** Debug line segments for this frame (ADR-0087): queue them in Extract or later; drawn over the scene, depth-tested. */
+    readonly debug: DebugLines;
+    /**
+     * Commands each frame records after the scene's uploads and before the frame graph, given the
+     * rigid vertex and index pools: GPU deformables writing the vertices this frame draws (ADR-0101)
+     * and, torn, their triangles (ADR-0104). WebGPU only.
+     */
+    readonly prepasses: ((encoder: GPUCommandEncoder, vertexPool: GPUBuffer, indexPool: GPUBuffer) => void)[];
+    readonly health: GpuHealth;
+    readonly profile: DeviceProfile;
+    readonly tier: Tier;
+    /** Every loaded mesh (CPU side; `meshes.add` returns the id `render.Mesh` stores). Mesh 0 is a unit cube. */
+    readonly meshes: MeshStore;
+    /** Every material (`materials.add` returns the id `render.Mesh.material` stores). Material 0 is white. */
+    readonly materials: MaterialStore;
+    /** Material textures (ADR-0060): two arrays in the family this device samples, one size class per tier. */
+    readonly textures: TextureStore;
+    /**
+     * The `render.Mesh` component (mesh id, material id, colour), or null without a world.
+     * Every entity with it and a `GlobalTransform` is drawn: the plugin extracts them itself.
+     */
+    readonly Mesh: Component | null;
+    /** Device recoveries this session. */
+    recoveries: number;
+    /** CPU time of the last frame's encode + submit (including the upload), in ms. */
+    submitMs: number;
+    /** CPU time of the last frame's instance upload (`writeBuffer` from linear memory), in ms. */
+    uploadMs: number;
+    /**
+     * The most frames submitted to the GPU and not yet finished (live; 0, the default: no cap). A browser
+     * that paces frames (vsync) never queues more than two or three; one that does not (a headless
+     * benchmark with no frame-rate limit) queues frames until the GPU is a second behind. With a cap, a
+     * frame whose turn comes while that many are in flight is not drawn (the world still steps), so
+     * the GPU is always busy and never behind (ADR-0129). Not for golden pages, which step the app in a
+     * loop and expect every frame drawn.
+     */
+    maxFramesInFlight: number;
+    /** Frames submitted and not yet finished on the GPU. */
+    readonly framesInFlight: number;
+    /** Frames not drawn because `maxFramesInFlight` were in flight. */
+    readonly skippedFrames: number;
+    /**
+     * Reads back the next frame exactly as drawn: RGBA8, `width × height × 4` bytes, top row
+     * first. Decoded pixels, not a screenshot (no colour conversion, no compositor); golden
+     * image tests compare these.
+     */
+    capture(): Promise<FrameCapture>;
+    /**
+     * Destroys the device as if the GPU process had crashed, to exercise recovery. The loss
+     * is reported as `unknown`. (A real `destroy()` reports `destroyed`, which is an
+     * intentional teardown and is never recovered.)
+     */
+    simulateDeviceLoss(): void;
+}
+/** One frame read back by `render.capture()`. */
+export interface FrameCapture {
+    readonly width: number;
+    readonly height: number;
+    /** RGBA8, rows top to bottom, no padding. */
+    readonly rgba: Uint8Array;
+}
+/** `@yali-engine/render` options. */
+export interface RenderPluginOptions {
+    /** The page's canvas, or the OffscreenCanvas a render worker received (`connectRenderWorker`). */
+    readonly canvas: HTMLCanvasElement | OffscreenCanvas;
+    /**
+     * `auto` (default): WebGPU (core, then compatibility mode), else WebGL2 where the browser
+     * has no WebGPU or no adapter (ADR-0070). `webgpu` never falls back; `webgl2` skips WebGPU
+     * (tests the fallback on a WebGPU machine).
+     */
+    readonly backend?: 'auto' | 'webgpu' | 'webgl2';
+    /** Initial instance capacity (grows on demand). */
+    readonly capacity?: number;
+    /** Force a tier instead of selecting one. */
+    readonly tier?: Tier;
+    /** Sizing policy (DPR cap, pixel cap, initial render scale). */
+    readonly viewport?: ViewportOptions;
+    /** Replay a recorded render bundle of the scene's draws (default true: 0.36 → 0.11 ms encode at 5,000 draws, ADR-0050). */
+    readonly bundles?: boolean;
+    /**
+     * Upload instances through a mapped staging ring. Default: on with a core WebGPU adapter
+     * (4–5× faster than `writeBuffer` under 4 MiB, measured in bench/webgpu-upload), off in
+     * compatibility mode, where mapping costs far more (Galaxy F04: 11.6 ms against 0.8 ms per
+     * 640 KB frame, ADR-0056).
+     */
+    readonly staging?: boolean;
+    /** Let the frame-budget governor lower the render scale under GPU load (default true). */
+    readonly dynamicResolution?: boolean;
+    /** Let the governor coarsen LODs and drop sub-pixel instances under GPU load (`render.lodBias`, default true). */
+    readonly dynamicLod?: boolean;
+    /**
+     * How instances reach the vertex stage (ADR-0045): `auto` (default) uses storage buffers
+     * when the device allows two in the vertex stage, else the compacted vertex-buffer path.
+     */
+    readonly instances?: 'auto' | 'storage' | 'vertex';
+    /**
+     * Who culls and picks LODs (ADR-0057): `gpu` (a compute pass feeding indirect draws),
+     * `cpu` (the extract, with ordinary draws), or `auto` (default): `cpu` in compatibility
+     * mode, where indirect draws measured ~9 ms per frame on a Galaxy F04, else `gpu`.
+     */
+    readonly cull?: 'auto' | 'gpu' | 'cpu';
+    /**
+     * Two-pass occlusion culling (ADR-0095): `occlusion()` from `@yali-engine/render/occlusion`. WebGPU's GPU
+     * cull on the storage path only (elsewhere it is off and `render.scene.occlusionActive` says so).
+     */
+    readonly occlusion?: import('./occlusion.ts').OcclusionFactory;
+    /**
+     * Cluster culling for big meshes (ADR-0100): `meshlets()` from `@yali-engine/render/meshlets`. The GPU
+     * cull's storage path only (elsewhere the meshes draw whole).
+     */
+    readonly meshlets?: import('./meshlets.ts').MeshletSupport;
+    /** Ask for a WebGPU compatibility-mode adapter first (tests the T0 path on desktop). */
+    readonly compat?: boolean;
+    /** Texels per side of a texture-array layer. Default per tier: T0 512, T1 1024, T2 2048 (ADR-0060). */
+    readonly textureSize?: number;
+    /** Force the texture family (default: the best the device samples, `pickFamily`). Textures must be that variant. */
+    readonly textureFamily?: TextureFamily;
+    /** The tone curve from the HDR scene to the screen (default `neutral`, Khronos PBR Neutral). */
+    readonly toneMapping?: ToneCurve;
+    /** Linear exposure before the tone curve (default 1). */
+    readonly exposure?: number;
+    /**
+     * Post-processing (ADR-0092): bloom, colour grading, TAA, FXAA, on WebGPU with the HDR
+     * target (asking for any turns `hdr` on unless it is set false). WebGL2 grades only.
+     */
+    readonly post?: PostOptions;
+    /** The procedural sky the environment lighting comes from (M2 increment 5). */
+    readonly sky?: SkyOptions;
+    /** The sun's colour and intensity and the ambient intensity (the sun's direction is `camera.lightDir`). */
+    readonly lighting?: Partial<LightingOptions>;
+    /** The sun's cascaded shadow maps (ADR-0068; default on, sized per tier), or `false` for none. */
+    readonly shadows?: ShadowOptions | false;
+    /**
+     * Draw into a half-float HDR target and tone-map it in a pass (default on T1 and T2). Off
+     * (T0's default, ADR-0071), the draw tone-maps inline and writes the display directly: the
+     * same curve per fragment, without the HDR target's bandwidth or the full-screen pass.
+     */
+    readonly hdr?: boolean;
+    /**
+     * Let the governor step the shading down under GPU load (`render.shading`, ADR-0072):
+     * full PBR, then Lambert with the ambient and the sun's shadow, then flat with no shadows.
+     * Default on T0, where full PBR costs a Galaxy F04 ~30 ms at 20k instances.
+     */
+    readonly dynamicShading?: boolean;
+    /**
+     * Benchmarks only: a transform of the linked draw shader, compiled beside it as extra shading
+     * levels (`SceneRenderer.shaderVariant`), for A/B measurements in one page.
+     */
+    readonly shaderVariant?: (wgsl: string) => string;
+    /**
+     * The device-filter table (DESIGN.md §14), instead of the engine's `DEVICE_FILTER`; spread
+     * that to extend it. A matching rule may lower the tier and turn features off; an option
+     * set explicitly here still wins over a turned-off feature.
+     */
+    readonly deviceFilter?: readonly DeviceFilterRule[];
+}
+/** The scene's colour target: linear HDR, tone-mapped to the swapchain by `post.tonemap`. */
+export declare const HDR_FORMAT: GPUTextureFormat;
+/**
+ * The render plugin (DESIGN.md §11–§14). It acquires a WebGPU device (core, then
+ * compatibility mode) or, where the browser has no WebGPU, falls back to WebGL2 (ADR-0070),
+ * selects the tier, draws extracted instances each frame (Submit stage), and rebuilds its
+ * whole device state after device loss without restarting the app (DESIGN.md §3).
+ *
+ * @example
+ * const app = App.create({ plugins: [renderPlugin({ canvas }), gamePlugin] });
+ * await app.init();
+ * app.start();
+ */
+export declare function renderPlugin(options: RenderPluginOptions): YaliPlugin;