@yali-engine/render 0.0.0-stage → 0.4.0

package/dist/meshlets-decoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meshlets-decoder.js","sourceRoot":"","sources":["../src/meshlets-decoder.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,6FAA6F;AAC7F,0FAA0F;AAC1F,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,EAAE,YAAY,EAAuB,MAAM,oBAAoB,CAAC;AAEvE,2HAA2H;AAC3H,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAExC;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,QAAsB,EAAE,OAAoB,EAAE,GAAY;IACvF,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,sBAAsB,GAAG,QAAQ,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzF,KAAK,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;IAC3B,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAC1B,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,YAAY,CAAC,KAAK,CAAC,MAAM,EAAE,sBAAsB,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC1F,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,sBAAsB,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7D,OAAO,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAAiB;IACtD,MAAM,IAAI,GAAG,IAAI,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,sBAAsB,CAAC,CAAC;IACrF,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACnB,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACnB,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC1B,MAAM,EAAE,GAAG,KAAK,CAAC,UAAU,GAAG,sBAAsB,GAAG,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,IAAI,YAAY,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;IAC/D,MAAM,kBAAkB,CAAC,KAAK,CAAC;IAC/B,IAAI,GAAG;QAAE,MAAM,iBAAiB,CAAC,KAAK,CAAC;IACvC,OAAO,YAAY,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;AAC9C,CAAC;AAED,oGAAoG;AACpG,OAAO,EAAE,iBAAiB,EAA8C,iBAAiB,EAAoB,UAAU,EAAkD,MAAM,oBAAoB,CAAC"}

package/dist/meshlets.d.ts

@@ -0,0 +1,186 @@
+import { type PackedClusters } from './cluster-build.ts';
+import { ClusterResidency } from './cluster-stream.ts';
+/** The hierarchy builder (ADR-0111), now in `cluster-build.ts` (ADR-0113). */
+export { buildClusterLod, packClusters, type PackedClusters } from './cluster-build.ts';
+import type { FrameGraph } from './frame-graph.ts';
+import type { MeshStore } from './meshes.ts';
+import type { LinkedShader, PipelineCache } from './pipeline-cache.ts';
+import type { ClusterHook, ClusterMotion, SceneRenderer } from './scene.ts';
+/** What `renderPlugin({ meshlets })` takes (ADR-0100). */
+export interface MeshletOptions {
+    /** Meshes with at least this many triangles in their finest LOD are clustered (default 4096). */
+    readonly minTriangles?: number;
+    /** The most cluster entries one frame may list (default 4M, 32 MB); a mesh whose instances could need more is drawn whole. */
+    readonly maxEntries?: number;
+    /**
+     * A cluster LOD hierarchy per mesh (ADR-0111, opt-in): groups of clusters simplified with their
+     * borders locked, level by level, and each instance draws the cut whose projected error is under
+     * the scene's `errorPx` (the instance LODs' threshold, `render.lodBias` included). Builds take
+     * ~8 ms per 1k triangles: give `pool` to make them on a decode worker.
+     */
+    readonly lod?: boolean;
+    /**
+     * Build the clusters on these decode workers (ADR-0113): a pool whose workers serve the
+     * `cluster-lod` decoder (`decodeClusterLod` from `@yali-engine/render/meshlets-decoder`). A mesh draws
+     * whole until its clusters arrive. Without it they are built on the main thread, as the mesh
+     * first appears.
+     */
+    readonly pool?: ClusterBuildPool;
+    /**
+     * Streamed cluster pages (ADR-0134): a mesh converted with `yali convert --clusters --stream` draws
+     * its root pages at once and fetches the rest by HTTP `Range` as the view's cut asks for them (with
+     * `lod`). `inFlight` caps concurrent fetches (default 8); `fetch` replaces the HTTP fetch (a cache, tests).
+     */
+    readonly stream?: {
+        readonly inFlight?: number;
+        readonly fetch?: PageFetch;
+    };
+}
+/** Fetches `length` bytes of `url` from `offset` (an HTTP `Range` request by default). */
+export type PageFetch = (url: string, offset: number, length: number) => Promise<Uint8Array>;
+/** The cluster cull without the page bits (devices with 8 storage buffers a stage): `note_pages` emptied, so the binding is unused. */
+export declare function withoutPageBits(s: LinkedShader): LinkedShader;
+/** What `meshlets({ pool })` needs of a decode pool (`DecodePool` from `@yali-engine/core` is one). */
+export interface ClusterBuildPool {
+    decode<T>(name: string, bytes: Uint8Array): Promise<T>;
+}
+/** The meshlet support `renderPlugin` builds when given it. */
+export interface MeshletSupport {
+    readonly options: MeshletOptions;
+    create(device: GPUDevice, scene: SceneRenderer, store: MeshStore): Promise<ClusterRenderer>;
+}
+/**
+ * Cluster culling for big meshes (ADR-0100): pass it as `renderPlugin({ meshlets: meshlets() })`.
+ *
+ * @example
+ * import { meshlets } from '@yali-engine/render/meshlets';
+ * renderPlugin({ canvas, meshlets: meshlets({ minTriangles: 8192 }) });
+ */
+export declare function meshlets(options?: MeshletOptions): MeshletSupport;
+export interface Clustered {
+    first: number;
+    count: number;
+    doubleSided: boolean;
+    /** Indices of all its clusters (an instance's most). */
+    indices: number;
+}
+/**
+ * Clusters on the CPU, in the layout the shaders read (ADR-0100, ADR-0111): 32 words per cluster
+ * (bounding sphere, normal cone, base vertex, where its vertices and triangle bytes start, its
+ * triangle count, flags, then its own and its parent's error spheres and errors, both 0 without a
+ * hierarchy), the clusters' local vertex indices, and their triangle bytes (each cluster's start
+ * rounded to 4). Pure: tested in Node.
+ */
+export declare class ClusterData {
+    words: Uint32Array<ArrayBuffer>;
+    f32: Float32Array<ArrayBuffer>;
+    count: number;
+    vertices: Uint32Array<ArrayBuffer>;
+    vertexCount: number;
+    triangles: Uint8Array<ArrayBuffer>;
+    triangleBytes: number;
+    meshes: number;
+    /**
+     * Clusters a mesh (interleaved vertices, 8 floats each; its finest LOD's indices) on this thread and
+     * appends them; with `lod`, its whole hierarchy (ADR-0111). Needs `MeshoptClusterizer.ready` (and
+     * the simplifier's for `lod`).
+     */
+    build(vertices: Float32Array, indices: Uint32Array, baseVertex: number, doubleSided: boolean, lod?: boolean): Clustered;
+    /**
+     * Appends one mesh's packed clusters (`packClusters`, here or on a decode worker, ADR-0113): moves
+     * their vertex and triangle offsets to where they land and sets the mesh's base vertex and side.
+     */
+    append(p: PackedClusters, baseVertex: number, doubleSided: boolean): Clustered;
+}
+/** The clustered meshes' data on the GPU, the cull passes and the draw. */
+export declare class ClusterRenderer implements ClusterHook {
+    #private;
+    readonly device: GPUDevice;
+    version: number;
+    /** The clusters on the CPU (uploaded when they grow). */
+    readonly data: ClusterData;
+    /** Occlusion for clusters (ADR-0109; live): off culls them once, after both instance passes, as ADR-0100 did. */
+    occlusion: boolean;
+    /**
+     * Clustered shadow casters (ADR-0112; live): with a hierarchy (`lod`), casters at the view's cut, culled
+     * per cascade and pulled; without one the cascades draw clustered meshes whole (pulled costs more there).
+     * Off, they draw whole always. (ADR-0122's indexed casters were removed: slower whole frames, ADR-0139.)
+     */
+    shadows: boolean;
+    /** Clustered motion (ADR-0112; live): off, the motion pass draws clustered meshes whole, as before. */
+    motion: boolean;
+    /** Streamed pages' residency (ADR-0134). */
+    readonly residency: ClusterResidency;
+    /** Pages fetched, their bytes, fetches that failed (ADR-0134). */
+    readonly streamStats: {
+        fetched: number;
+        bytes: number;
+        failed: number;
+    };
+    /** Meshes clustered and their clusters (for the counters). */
+    get stats(): {
+        meshes: number;
+        clusters: number;
+    };
+    constructor(device: GPUDevice, scene: SceneRenderer, store: MeshStore, o: MeshletOptions);
+    init(cache: PipelineCache): Promise<void>;
+    /** Whether mesh `mesh`'s finest LOD is drawn as clusters (the main view's slot then skips it). */
+    covers(mesh: number): boolean;
+    /** Meshes clustered on the pool and the milliseconds from request to arrival, summed (ADR-0113); meshes whose file carried their clusters (ADR-0121). */
+    readonly buildStats: {
+        meshes: number;
+        ms: number;
+        prebuilt: number;
+    };
+    /** Cluster builds still on the pool. */
+    get pending(): number;
+    /**
+     * Resolves when the clustered draw's pipelines for the current draw shader are built, and every
+     * mesh the store holds now has its clusters (the pool's builds arrived, ADR-0113).
+     */
+    ready(): Promise<void>;
+    /**
+     * Draws frames until streamed pages stop arriving (ADR-0134): calls `frame` (one frame drawn) until no
+     * page is in flight or being asked for and none arrived for 8 frames in a row, at most `most` frames.
+     * For golden images, whose frame must not depend on when pages came. Immediate with nothing streamed.
+     */
+    settled(frame: () => void, most?: number): Promise<void>;
+    /**
+     * Adds a cluster cull, reading the instance cull's `after` (ADR-0100, ADR-0109): `phase` 0 without
+     * occlusion; under occlusion 1 (after the first instance cull, drawn in the view's first pass) and
+     * 2 (after the recheck, drawn in the second).
+     */
+    addCull(graph: FrameGraph, after: string, phase?: 0 | 1 | 2): void;
+    /** Draws phase `phase`'s visible clusters (in the scene's opaque pass it is called from). */
+    encodeDraw(pass: GPURenderPassEncoder, phase?: 0 | 1 | 2): void;
+    /**
+     * Adds the shadow casters' cluster cull after `after` (the instance cull, whose slot set 0 holds the
+     * casters): every cascade at once, read by `scene.shadow` (ADR-0112).
+     */
+    addShadowCull(graph: FrameGraph, after: string): void;
+    /** Whether this frame's casters of mesh `mesh` are drawn as clusters (the cascades' slots then skip it). */
+    shadowCovers(mesh: number): boolean;
+    /** Draws cascade `cascade`'s clustered casters into the shadow pass (its viewport already set). */
+    encodeShadow(pass: GPURenderPassEncoder, cascade: number): void;
+    /**
+     * Whether the motion pass may skip the clustered meshes' slots: the clustered motion pipeline over
+     * `m`'s shader is built (it starts building on the first call).
+     */
+    motionCovers(m: ClusterMotion): boolean;
+    /** Starts building the clustered motion pipeline over the motion pass's shader (`ready()` then awaits it). */
+    prepareMotion(motionShader: LinkedShader, format: GPUTextureFormat): void;
+    /** Draws the clusters this frame's view drew (every phase that ran) with the motion pipeline. */
+    encodeMotion(pass: GPURenderPassEncoder, m: ClusterMotion): void;
+    /** Clusters the last frame drew, over its phases: single- and double-sided (a diagnostic; reads back from the GPU). */
+    readCounts(): Promise<{
+        single: number;
+        double: number;
+        triangles: number;
+        drawReady: boolean;
+        jobs: number;
+        perPhase: number[];
+        shadow: number[];
+        motionReady: boolean;
+    }>;
+    destroy(): void;
+}