@yali-engine/render 0.0.0-stage → 0.4.0

package/dist/cluster-stream.d.ts

@@ -0,0 +1,83 @@
+import { type DecodedPage } from './cluster-pages.ts';
+/** What the residency needs of the cluster arrays (`ClusterData`). */
+export interface ClusterArrays {
+    words: Uint32Array;
+    vertices: Uint32Array;
+    triangles: Uint8Array;
+}
+/** One streamed mesh as `addMesh` takes it: the file's page table and where its clusters and vertices landed. */
+export interface StreamedMeshLayout {
+    /** The mesh's first cluster record (`Clustered.first`). */
+    readonly first: number;
+    /** `PAGE_WORDS` a page; the clusters in page order (`ClusterPages.pages`). */
+    readonly table: Uint32Array;
+    readonly roots: number;
+    readonly slotVertices: number;
+    /** The mesh's first vertex in the pool (its root pages' vertices from there, then the slots). */
+    readonly baseVertex: number;
+    /** Vertices before the slots (its root pages'). */
+    readonly rootVertices: number;
+    /** Page slots after the roots. */
+    readonly slots: number;
+}
+/** A vertex block to write into the pool: the mesh-relative first vertex and the data. */
+export interface VertexWrite {
+    readonly mesh: number;
+    readonly first: number;
+    readonly data: Float32Array;
+}
+/**
+ * The residency of every streamed mesh's pages (ADR-0134). Root pages are resident from the start and
+ * never leave; another page arrives only after the page holding its parents (requests come from drawn
+ * leaves), and leaves only after its own children (children first), so the cut never has a hole:
+ * a cluster whose page is missing is never drawn, and one whose children's page is missing is drawn as
+ * a leaf (`STREAM_LEAF`: its own error counted as 0).
+ */
+export declare class ClusterResidency {
+    #private;
+    /** Pages evicted, loaded, and requests dropped for want of a slot. */
+    readonly stats: {
+        loaded: number;
+        evicted: number;
+        starved: number;
+    };
+    /** Pages over every mesh (the cull's page bits cover this many). */
+    get pageCount(): number;
+    /** Pages on the GPU now. */
+    get resident(): number;
+    /** Pages being fetched. */
+    get inFlight(): number;
+    /**
+     * Registers a mesh whose records were appended (vertex and triangle offsets already moved, base
+     * vertex the mesh's): numbers its pages globally, sets every record's flags, and applies its root
+     * pages (`roots`, decoded, in page order). Returns the mesh's index.
+     */
+    addMesh(d: ClusterArrays, layout: StreamedMeshLayout, roots: readonly DecodedPage[]): number;
+    /**
+     * One read of the cull's page bits (`needed`, `used`: a bit per global page, a frame or so old):
+     * marks what was seen, and returns the pages to fetch now (not resident, not in flight, their parents
+     * resident), at most `room`, coarse (lower page ids) first.
+     */
+    requests(d: ClusterArrays, needed: Uint32Array, used: Uint32Array, room: number): number[];
+    /** Where page `g` is in its mesh's page data: the table's byte offset and length, and the mesh. */
+    locate(g: number): {
+        mesh: number;
+        offset: number;
+        length: number;
+    };
+    /** A fetch that failed or was abandoned: the page may be asked for again. */
+    cancel(g: number): void;
+    /**
+     * A fetched page arrived: takes a free slot of its mesh or evicts the least recently seen page that
+     * has no resident children (and was not seen in the last read), then applies it. False when no slot
+     * could be had (the request is dropped; its parents stay leaves).
+     */
+    load(d: ClusterArrays, g: number, page: DecodedPage): boolean;
+    /** What changed since the last call: records to re-upload, local-id and triangle-byte ranges, vertex blocks. */
+    takeDirty(): {
+        records: number[];
+        ids: [number, number][];
+        triangles: [number, number][];
+        vertices: VertexWrite[];
+    };
+}

package/dist/cluster-stream.js

@@ -0,0 +1,226 @@
+// Page residency for streamed cluster hierarchies (ADR-0134): which pages are on the GPU, where their
+// vertices live, and the residency flags in each cluster record that keep the cut whole. Pure: it
+// edits `ClusterData`'s CPU arrays and reports what changed; `@yali-engine/render/meshlets` fetches, uploads
+// and reads the cull's page bits. Tested in Node.
+import { YaliError } from '@yali-engine/core';
+import { CLUSTER_WORDS } from "./cluster-build.js";
+import { KIDS_WORD, PAGE_WORDS, STREAM_LEAF, STREAM_MISSING, STREAM_WORD } from "./cluster-pages.js";
+/**
+ * The residency of every streamed mesh's pages (ADR-0134). Root pages are resident from the start and
+ * never leave; another page arrives only after the page holding its parents (requests come from drawn
+ * leaves), and leaves only after its own children (children first), so the cut never has a hole:
+ * a cluster whose page is missing is never drawn, and one whose children's page is missing is drawn as
+ * a leaf (`STREAM_LEAF`: its own error counted as 0).
+ */
+export class ClusterResidency {
+    #pages = [];
+    #meshes = [];
+    #reads = 0;
+    /** Cluster records, local-id words and triangle bytes changed since `takeDirty` (record indices; [start, end) ranges). */
+    #dirtyRecords = new Set();
+    #dirtyIds = [];
+    #dirtyTris = [];
+    #writes = [];
+    /** Pages evicted, loaded, and requests dropped for want of a slot. */
+    stats = { loaded: 0, evicted: 0, starved: 0 };
+    /** Pages over every mesh (the cull's page bits cover this many). */
+    get pageCount() {
+        return this.#pages.length;
+    }
+    /** Pages on the GPU now. */
+    get resident() {
+        let n = 0;
+        for (const p of this.#pages)
+            if (p.resident)
+                n++;
+        return n;
+    }
+    /** Pages being fetched. */
+    get inFlight() {
+        let n = 0;
+        for (const p of this.#pages)
+            if (p.inFlight)
+                n++;
+        return n;
+    }
+    /**
+     * Registers a mesh whose records were appended (vertex and triangle offsets already moved, base
+     * vertex the mesh's): numbers its pages globally, sets every record's flags, and applies its root
+     * pages (`roots`, decoded, in page order). Returns the mesh's index.
+     */
+    addMesh(d, layout, roots) {
+        const mesh = this.#meshes.length;
+        const pageBase = this.#pages.length;
+        const np = layout.table.length / PAGE_WORDS;
+        for (let p = 0; p < np; p++)
+            this.#pages.push({ mesh, local: p, resident: false, inFlight: false, slot: -1, seen: 0, children: [], parents: [], residentChildren: 0 });
+        this.#meshes.push({ layout, pageBase, free: Array.from({ length: layout.slots }, (_, k) => layout.slots - 1 - k) });
+        for (let p = 0; p < np; p++) {
+            const page = this.#pages[pageBase + p];
+            const [first, count] = layout.table.subarray(p * PAGE_WORDS, p * PAGE_WORDS + 2);
+            const kids = new Set();
+            for (let c = layout.first + first; c < layout.first + first + count; c++) {
+                const o = c * CLUSTER_WORDS;
+                const k = d.words[o + KIDS_WORD];
+                d.words[o + STREAM_WORD] = ((pageBase + p) << 2) | STREAM_MISSING;
+                if (k > 0) {
+                    const g = pageBase + k - 1;
+                    d.words[o + KIDS_WORD] = g + 1;
+                    d.words[o + STREAM_WORD] |= STREAM_LEAF;
+                    kids.add(g);
+                    this.#pages[g].parents.push(c);
+                }
+                this.#dirtyRecords.add(c);
+            }
+            page.children.push(...kids);
+        }
+        // The roots: their vertices at the start of the mesh's block, one page after another.
+        let at = 0;
+        for (let p = 0; p < layout.roots; p++) {
+            this.#apply(d, pageBase + p, roots[p], at);
+            at += roots[p].vertices.length / 8;
+        }
+        return mesh;
+    }
+    /**
+     * One read of the cull's page bits (`needed`, `used`: a bit per global page, a frame or so old):
+     * marks what was seen, and returns the pages to fetch now (not resident, not in flight, their parents
+     * resident), at most `room`, coarse (lower page ids) first.
+     */
+    requests(d, needed, used, room) {
+        const r = ++this.#reads;
+        const out = [];
+        for (let w = 0; w < needed.length; w++) {
+            let bits = needed[w] | used[w];
+            while (bits) {
+                const b = 31 - Math.clz32(bits & -bits);
+                bits &= bits - 1;
+                const g = w * 32 + b;
+                const p = this.#pages[g];
+                if (!p)
+                    continue;
+                p.seen = r;
+                if ((needed[w] >>> b) & 1 && !p.resident && !p.inFlight && out.length < room && this.#parentsResident(d, g))
+                    out.push(g);
+            }
+        }
+        for (const g of out)
+            this.#pages[g].inFlight = true;
+        return out;
+    }
+    /** Where page `g` is in its mesh's page data: the table's byte offset and length, and the mesh. */
+    locate(g) {
+        const p = this.#pages[g];
+        const t = this.#meshes[p.mesh].layout.table;
+        return { mesh: p.mesh, offset: t[p.local * PAGE_WORDS + 3], length: t[p.local * PAGE_WORDS + 4] };
+    }
+    /** A fetch that failed or was abandoned: the page may be asked for again. */
+    cancel(g) {
+        this.#pages[g].inFlight = false;
+    }
+    /**
+     * A fetched page arrived: takes a free slot of its mesh or evicts the least recently seen page that
+     * has no resident children (and was not seen in the last read), then applies it. False when no slot
+     * could be had (the request is dropped; its parents stay leaves).
+     */
+    load(d, g, page) {
+        const p = this.#pages[g];
+        p.inFlight = false;
+        if (p.resident || !this.#parentsResident(d, g))
+            return false;
+        const m = this.#meshes[p.mesh];
+        let slot = m.free.pop();
+        if (slot === undefined) {
+            let victim = -1;
+            const keep = this.#parentPages(d, g);
+            for (let q = m.pageBase + m.layout.roots; q < m.pageBase + m.layout.table.length / PAGE_WORDS; q++) {
+                const v = this.#pages[q];
+                if (!v.resident || v.residentChildren > 0 || v.seen >= this.#reads || keep.has(q))
+                    continue;
+                if (victim < 0 || v.seen < this.#pages[victim].seen)
+                    victim = q;
+            }
+            if (victim < 0) {
+                this.stats.starved++;
+                return false;
+            }
+            this.#evict(d, victim);
+            slot = m.free.pop();
+        }
+        this.#apply(d, g, page, m.layout.rootVertices + slot * m.layout.slotVertices, slot);
+        this.stats.loaded++;
+        return true;
+    }
+    #parentsResident(d, g) {
+        for (const c of this.#pages[g].parents)
+            if ((d.words[c * CLUSTER_WORDS + STREAM_WORD] & STREAM_MISSING) !== 0)
+                return false;
+        return true;
+    }
+    /** The pages holding page `g`'s parents. */
+    #parentPages(d, g) {
+        const out = new Set();
+        for (const c of this.#pages[g].parents)
+            out.add(d.words[c * CLUSTER_WORDS + STREAM_WORD] >>> 2);
+        return out;
+    }
+    #apply(d, g, page, at, slot = -1) {
+        const p = this.#pages[g];
+        const m = this.#meshes[p.mesh];
+        const [first, count, vcount] = m.layout.table.subarray(p.local * PAGE_WORDS, p.local * PAGE_WORDS + 3);
+        if (page.vertices.length !== vcount * 8)
+            throw new YaliError('PAGE_MISMATCH', `Cluster page ${p.local} has ${page.vertices.length / 8} vertices; the file's table says ${vcount}.`, 'The .pages.bin does not belong to this GLB: convert again and serve both files together.');
+        const c0 = m.layout.first + first;
+        const ids = d.words[c0 * CLUSTER_WORDS + 12];
+        const tris = d.words[c0 * CLUSTER_WORDS + 13];
+        d.vertices.set(page.ids, ids);
+        d.triangles.set(page.triangles, tris);
+        this.#dirtyIds.push([ids, ids + page.ids.length]);
+        this.#dirtyTris.push([tris, tris + page.triangles.length]);
+        for (let c = c0; c < c0 + count; c++) {
+            const o = c * CLUSTER_WORDS;
+            d.words[o + 11] = m.layout.baseVertex + at;
+            d.words[o + STREAM_WORD] &= ~STREAM_MISSING;
+            this.#dirtyRecords.add(c);
+        }
+        for (const c of p.parents) {
+            d.words[c * CLUSTER_WORDS + STREAM_WORD] &= ~STREAM_LEAF;
+            this.#dirtyRecords.add(c);
+        }
+        this.#parentPage(d, g, +1);
+        p.resident = true;
+        p.slot = slot;
+        p.seen = this.#reads;
+        this.#writes.push({ mesh: p.mesh, first: at, data: page.vertices });
+    }
+    #evict(d, g) {
+        const p = this.#pages[g];
+        const m = this.#meshes[p.mesh];
+        const [first, count] = m.layout.table.subarray(p.local * PAGE_WORDS, p.local * PAGE_WORDS + 2);
+        for (let c = m.layout.first + first; c < m.layout.first + first + count; c++) {
+            d.words[c * CLUSTER_WORDS + STREAM_WORD] |= STREAM_MISSING;
+            this.#dirtyRecords.add(c);
+        }
+        for (const c of p.parents) {
+            d.words[c * CLUSTER_WORDS + STREAM_WORD] |= STREAM_LEAF;
+            this.#dirtyRecords.add(c);
+        }
+        this.#parentPage(d, g, -1);
+        p.resident = false;
+        m.free.push(p.slot);
+        p.slot = -1;
+        this.stats.evicted++;
+    }
+    /** The pages holding page `g`'s parents gain or lose a resident child. */
+    #parentPage(d, g, by) {
+        for (const q of this.#parentPages(d, g))
+            this.#pages[q].residentChildren += by;
+    }
+    /** What changed since the last call: records to re-upload, local-id and triangle-byte ranges, vertex blocks. */
+    takeDirty() {
+        const out = { records: [...this.#dirtyRecords].sort((a, b) => a - b), ids: this.#dirtyIds.splice(0), triangles: this.#dirtyTris.splice(0), vertices: this.#writes.splice(0) };
+        this.#dirtyRecords.clear();
+        return out;
+    }
+}
+//# sourceMappingURL=cluster-stream.js.map

package/dist/cluster-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-stream.js","sourceRoot":"","sources":["../src/cluster-stream.ts"],"names":[],"mappings":"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"}

package/dist/culled-draws.d.ts

@@ -0,0 +1,30 @@
+import { type MeshEntry } from './meshes.ts';
+/** Most cascades the CPU cull partitions by (`CULL_CASCADES` in the core). */
+export declare const CULL_CASCADES = 3;
+/**
+ * The draws of a CPU-culled frame (ADR-0057, ADR-0073), built from the core's per-bin counts:
+ * the main pass draws each (mesh, LOD) slot whole, and shadow cascade c draws only the runs of
+ * the slot's groups whose instances reach it. Draws are 5 words: index count, first index,
+ * base vertex, first instance, instance count. Reused frame to frame; it allocates only to grow.
+ */
+export declare class CulledDraws {
+    main: Uint32Array<ArrayBuffer>;
+    /** Each main draw's draw class (ADR-0081). */
+    mainClass: Uint8Array<ArrayBuffer>;
+    mainCount: number;
+    /** Per cascade: its draws, and how many. */
+    readonly cascade: Uint32Array<ArrayBuffer>[];
+    readonly cascadeCount: number[];
+    /** Each cascade draw's draw class (blend classes cast no shadow, so never appear). */
+    readonly cascadeClass: Uint8Array<ArrayBuffer>[];
+    /** Instances drawn at each LOD (index 0 = full detail). */
+    readonly byLod: Uint32Array<ArrayBuffer>;
+    /** Instances each cascade draws (its casters), and the main pass (`mainInstances`). */
+    readonly casters: number[];
+    mainInstances: number;
+    /**
+     * Reads `meshes × 8 × 2^cascades` counts from `u32[at…]` (bins mesh-major, then LOD, then
+     * group) and lays the slots out back to back from instance 0, as the core wrote them.
+     */
+    build(u32: Uint32Array, at: number, meshes: number, entries: readonly MeshEntry[], cascades: number): void;
+}

package/dist/culled-draws.js

@@ -0,0 +1,103 @@
+import { isBlendClass } from "./meshes.js";
+/** Most cascades the CPU cull partitions by (`CULL_CASCADES` in the core). */
+export const CULL_CASCADES = 3;
+/** Each cascade count's group order (`CASCADE_ORDER` in the core): group g holds cascade mask `order[g]`. */
+const CASCADE_ORDER = [[0], [1, 0], [1, 3, 2, 0], [1, 3, 7, 5, 6, 2, 4, 0]];
+/**
+ * The draws of a CPU-culled frame (ADR-0057, ADR-0073), built from the core's per-bin counts:
+ * the main pass draws each (mesh, LOD) slot whole, and shadow cascade c draws only the runs of
+ * the slot's groups whose instances reach it. Draws are 5 words: index count, first index,
+ * base vertex, first instance, instance count. Reused frame to frame; it allocates only to grow.
+ */
+export class CulledDraws {
+    main = new Uint32Array(0);
+    /** Each main draw's draw class (ADR-0081). */
+    mainClass = new Uint8Array(0);
+    mainCount = 0;
+    /** Per cascade: its draws, and how many. */
+    cascade = [new Uint32Array(0), new Uint32Array(0), new Uint32Array(0)];
+    cascadeCount = [0, 0, 0];
+    /** Each cascade draw's draw class (blend classes cast no shadow, so never appear). */
+    cascadeClass = [new Uint8Array(0), new Uint8Array(0), new Uint8Array(0)];
+    /** Instances drawn at each LOD (index 0 = full detail). */
+    byLod = new Uint32Array(8);
+    /** Instances each cascade draws (its casters), and the main pass (`mainInstances`). */
+    casters = [0, 0, 0];
+    mainInstances = 0;
+    /**
+     * Reads `meshes × 8 × 2^cascades` counts from `u32[at…]` (bins mesh-major, then LOD, then
+     * group) and lays the slots out back to back from instance 0, as the core wrote them.
+     */
+    build(u32, at, meshes, entries, cascades) {
+        const groups = 1 << cascades;
+        const order = CASCADE_ORDER[cascades];
+        const grow = (a, n) => (a.length >= n ? a : new Uint32Array(2 ** Math.ceil(Math.log2(Math.max(1, n)))));
+        this.main = grow(this.main, meshes * 8 * 5);
+        if (this.mainClass.length < meshes * 8)
+            this.mainClass = new Uint8Array(this.main.length / 5);
+        // A cascade has at most two runs per slot.
+        for (let c = 0; c < cascades; c++) {
+            this.cascade[c] = grow(this.cascade[c], meshes * 8 * 2 * 5);
+            if (this.cascadeClass[c].length < meshes * 8 * 2)
+                this.cascadeClass[c] = new Uint8Array(this.cascade[c].length / 5);
+        }
+        this.byLod.fill(0);
+        this.cascadeCount.fill(0);
+        this.casters.fill(0);
+        let n = 0;
+        let start = 0;
+        for (let m = 0; m < meshes; m++) {
+            const e = entries[m];
+            for (let l = 0; l < 8; l++) {
+                const bin = (m * 8 + l) * groups;
+                let total = 0;
+                for (let g = 0; g < groups; g++)
+                    total += u32[at + bin + g];
+                if (total === 0)
+                    continue;
+                const lod = e.lods[l] ?? e.lods[0];
+                const d = this.main;
+                d[n * 5] = lod.count;
+                d[n * 5 + 1] = lod.firstIndex;
+                d[n * 5 + 2] = e.baseVertex;
+                d[n * 5 + 3] = start;
+                d[n * 5 + 4] = total;
+                this.mainClass[n] = e.drawClass;
+                n++;
+                this.byLod[l] += total;
+                // A blended mesh casts no shadow (ADR-0081).
+                for (let c = 0; c < (isBlendClass(e.drawClass) ? 0 : cascades); c++) {
+                    const out = this.cascade[c];
+                    let first = start;
+                    let runStart = -1;
+                    let k = this.cascadeCount[c];
+                    for (let g = 0; g <= groups; g++) {
+                        const inside = g < groups && (order[g] & (1 << c)) !== 0;
+                        const size = g < groups ? u32[at + bin + g] : 0;
+                        if (inside && runStart < 0)
+                            runStart = first;
+                        if (!inside && runStart >= 0) {
+                            if (first > runStart) {
+                                out[k * 5] = lod.count;
+                                out[k * 5 + 1] = lod.firstIndex;
+                                out[k * 5 + 2] = e.baseVertex;
+                                out[k * 5 + 3] = runStart;
+                                out[k * 5 + 4] = first - runStart;
+                                this.cascadeClass[c][k] = e.drawClass;
+                                this.casters[c] += first - runStart;
+                                k++;
+                            }
+                            runStart = -1;
+                        }
+                        first += size;
+                    }
+                    this.cascadeCount[c] = k;
+                }
+                start += total;
+            }
+        }
+        this.mainCount = n;
+        this.mainInstances = start;
+    }
+}
+//# sourceMappingURL=culled-draws.js.map

package/dist/culled-draws.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"culled-draws.js","sourceRoot":"","sources":["../src/culled-draws.ts"],"names":[],"mappings":"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"}

package/dist/debug-lines.d.ts

@@ -0,0 +1,51 @@
+import type { OrbitCamera } from './camera.ts';
+import type { PipelineCache } from './pipeline-cache.ts';
+/** Bytes per debug vertex: x, y, z (f32, camera-relative once queued) and an RGBA8 colour. */
+export declare const DEBUG_VERTEX_BYTES = 16;
+/**
+ * Debug line segments for this frame (`render.debug`, ADR-0087): plugins queue them after the
+ * camera has moved (Extract or later), the renderer draws them at the end of the scene pass,
+ * depth-tested against it, and the queue empties every frame. Positions are converted to
+ * camera-relative f32 as they are queued, from f64 origins, so lines far from the world origin
+ * stay exact. Allocation-free once the buffer has grown.
+ *
+ * @example
+ * const render = app.resource<RenderContext>('render');
+ * render.debug.line([0, 0, 0], [0, 2, 0], 0xff0000ff); // a red post, 2 m tall
+ */
+export declare class DebugLines {
+    #private;
+    /** Vertices queued this frame (two per segment). */
+    count: number;
+    /** At most this many vertices per frame; more are dropped (and counted). */
+    capacity: number;
+    /** Vertices dropped this frame over `capacity`. */
+    dropped: number;
+    /** Vertices the last drawn frame had (what `clear` emptied; the `render.debugLines` counter). */
+    drawn: number;
+    constructor(camera: OrbitCamera, capacity?: number);
+    /** The queued vertices (`count × 16` bytes from offset 0). */
+    get data(): Float32Array;
+    /**
+     * Queues `count` vertices from a packed buffer: 16 bytes each (x, y, z as f32 relative to
+     * `origin`, then RGBA8), starting at vertex `first` of the views `f32` / `u32` (one buffer,
+     * e.g. WASM memory). `origin` is f64 world coordinates.
+     */
+    add(f32: Float32Array, u32: Uint32Array, first: number, count: number, origin: ArrayLike<number>): void;
+    /** Queues one segment between world points `a` and `b`, colour `rgba` (red in the low byte). */
+    line(a: ArrayLike<number>, b: ArrayLike<number>, rgba: number): void;
+    /** Empties the queue (the renderer calls it after each frame). */
+    clear(): void;
+}
+/** Draws a `DebugLines` queue in the scene pass (WebGPU). */
+export declare class DebugLinesPass {
+    #private;
+    readonly device: GPUDevice;
+    constructor(device: GPUDevice, format: GPUTextureFormat, camera: GPUBuffer);
+    init(cache: PipelineCache): Promise<void>;
+    /** Uploads and draws `lines` into `pass` (inside the scene pass, after its draws). */
+    encode(pass: GPURenderPassEncoder, lines: DebugLines): void;
+    /** GPU buffers held (the leak check). */
+    get liveBuffers(): number;
+    destroy(): void;
+}