@yali-engine/render 0.0.0-stage → 0.4.0

package/dist/environment.js

@@ -0,0 +1,204 @@
+import { envSky } from "./shaders.gen.js";
+/** The default sky. */
+export const DEFAULT_SKY = {
+    sun: [0.45, 0.8, 0.4],
+    zenith: [0.18, 0.32, 0.62],
+    horizon: [0.62, 0.68, 0.74],
+    ground: [0.16, 0.14, 0.12],
+    sunDisk: [60, 56, 50],
+    sunAngle: 1.2,
+};
+/** Texels per cube face at the base level, and its mip count. */
+export const ENV_SIZE = 128;
+// Down to 4×4: a 1×1 face shows rough reflections as six flat cube faces.
+export const ENV_MIPS = 6;
+const SIZE = ENV_SIZE;
+const MIPS = ENV_MIPS;
+/** Bytes per uniform slot (one per face and mip; dynamic offsets need 256-byte alignment). */
+const SLOT = 256;
+const FACES = 6;
+/**
+ * The environment for image-based lighting (M2 increment 5): a procedural sky rendered into a
+ * cube map, each lower mip GGX-prefiltered for its roughness (`shaders/env/sky.wesl`), and the
+ * same sky projected onto nine spherical-harmonic coefficients for diffuse irradiance (CPU).
+ * Built once at start and again when `setSky` changes it; render passes only, so compatibility
+ * mode can run it. The draw reads `prefiltered` and `sh9`.
+ */
+export class Environment {
+    device;
+    /** Cube map the draw samples by roughness (mip m: roughness m / (mips − 1)). */
+    prefiltered;
+    mips = MIPS;
+    /** Irradiance / π as SH9, 9 × vec4 (rgb, 0): the draw's diffuse ambient for a normal n. */
+    sh9 = new Float32Array(36);
+    /** Bumped when the cube or SH changed. */
+    version = 0;
+    #base;
+    #sky = { ...DEFAULT_SKY };
+    #params;
+    #skyPipeline;
+    #filterPipeline;
+    #layout;
+    #sampler;
+    constructor(device) {
+        this.device = device;
+        const cube = (label) => device.createTexture({
+            label,
+            size: { width: SIZE, height: SIZE, depthOrArrayLayers: FACES },
+            mipLevelCount: MIPS,
+            format: 'rgba16float',
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC | GPUTextureUsage.COPY_DST,
+            textureBindingViewDimension: 'cube',
+        });
+        this.#base = cube('yali:env:base');
+        this.prefiltered = cube('yali:env:prefiltered');
+        this.#params = device.createBuffer({ label: 'yali:env:params', size: SLOT * FACES * MIPS, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        this.#sampler = device.createSampler({ label: 'yali:env', magFilter: 'linear', minFilter: 'linear', mipmapFilter: 'linear' });
+        this.#layout = device.createBindGroupLayout({
+            label: 'yali:env',
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.FRAGMENT, buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: 96 } },
+                { binding: 1, visibility: GPUShaderStage.FRAGMENT, texture: { viewDimension: 'cube' } },
+                { binding: 2, visibility: GPUShaderStage.FRAGMENT, sampler: {} },
+            ],
+        });
+    }
+    async init(cache) {
+        // An explicit layout (dynamic uniform offsets): created here, not through the cache, whose
+        // pipelines use `auto` layouts; the shader module still comes from it.
+        const layout = this.device.createPipelineLayout({ label: 'yali:env', bindGroupLayouts: [this.#layout] });
+        const module = await cache.module(envSky, 'yali:env');
+        const make = (entry) => this.device.createRenderPipelineAsync({
+            label: `yali:env:${entry}`,
+            layout,
+            vertex: { module, entryPoint: 'vs' },
+            fragment: { module, entryPoint: entry, targets: [{ format: 'rgba16float' }] },
+            primitive: { topology: 'triangle-list' },
+        });
+        [this.#skyPipeline, this.#filterPipeline] = await Promise.all([make('fs_sky'), make('fs_prefilter')]);
+        this.build();
+    }
+    /** Changes the sky (unset fields keep their values) and rebuilds the cube and SH. */
+    setSky(sky) {
+        this.#sky = mergeSky(this.#sky, sky);
+        this.build();
+    }
+    /** The current sky. */
+    get sky() {
+        return this.#sky;
+    }
+    /** Renders the sky into every mip of the base cube, then prefilters; projects SH9. */
+    build() {
+        const slots = new Float32Array((SLOT / 4) * FACES * MIPS);
+        for (let m = 0; m < MIPS; m++)
+            for (let f = 0; f < FACES; f++)
+                packSkyParams(slots, ((m * FACES + f) * SLOT) / 4, this.#sky, m, f);
+        this.device.queue.writeBuffer(this.#params, 0, slots);
+        const group = (source) => this.device.createBindGroup({
+            layout: this.#layout,
+            entries: [
+                { binding: 0, resource: { buffer: this.#params, size: 96 } },
+                { binding: 1, resource: source.createView({ dimension: 'cube' }) },
+                { binding: 2, resource: this.#sampler },
+            ],
+        });
+        // The sky pass reads no texture; bind the prefiltered cube as a dummy (never sampled).
+        const skyGroup = group(this.prefiltered);
+        const filterGroup = group(this.#base);
+        const enc = this.device.createCommandEncoder({ label: 'yali:env:build' });
+        const draw = (target, m, f, pipeline, g) => {
+            const pass = enc.beginRenderPass({
+                colorAttachments: [{ view: target.createView({ dimension: '2d', baseMipLevel: m, mipLevelCount: 1, baseArrayLayer: f, arrayLayerCount: 1 }), loadOp: 'clear', storeOp: 'store', clearValue: { r: 0, g: 0, b: 0, a: 1 } }],
+            });
+            pass.setPipeline(pipeline);
+            pass.setBindGroup(0, g, [(m * FACES + f) * SLOT]);
+            pass.draw(3);
+            pass.end();
+        };
+        for (let m = 0; m < MIPS; m++)
+            for (let f = 0; f < FACES; f++)
+                draw(this.#base, m, f, this.#skyPipeline, skyGroup);
+        enc.copyTextureToTexture({ texture: this.#base, mipLevel: 0 }, { texture: this.prefiltered, mipLevel: 0 }, { width: SIZE, height: SIZE, depthOrArrayLayers: FACES });
+        for (let m = 1; m < MIPS; m++)
+            for (let f = 0; f < FACES; f++)
+                draw(this.prefiltered, m, f, this.#filterPipeline, filterGroup);
+        this.device.queue.submit([enc.finish()]);
+        skySh9(this.sh9, this.#sky);
+        this.version++;
+    }
+    destroy() {
+        this.#base.destroy();
+        this.prefiltered.destroy();
+        this.#params.destroy();
+    }
+}
+/** `sky` with `changes`' set fields applied. */
+export function mergeSky(sky, changes) {
+    return { ...sky, ...Object.fromEntries(Object.entries(changes).filter(([, v]) => v !== undefined)) };
+}
+/** The sky pass's `SkyParams` (24 floats) for cube face `f` of mip `m`, at `out[o]`: every backend packs it so. */
+export function packSkyParams(out, o, s, m, f) {
+    const sun = normalize(s.sun);
+    out.set([...sun, m / (MIPS - 1)], o);
+    out.set([...s.zenith, 0, ...s.horizon, 0, ...s.ground, 0], o + 4);
+    out.set([...s.sunDisk, Math.cos((s.sunAngle * Math.PI) / 180)], o + 16);
+    out.set([f, SIZE, MIPS, 0], o + 20);
+}
+/** The SH9 irradiance of sky `s` (`Environment.sh9`), into `out`. */
+export function skySh9(out, s) {
+    const sun = normalize(s.sun);
+    projectSh9(out, (d) => skyRadiance(s, sun, d));
+}
+function normalize(v) {
+    const l = Math.hypot(v[0], v[1], v[2]) || 1;
+    return [v[0] / l, v[1] / l, v[2] / l];
+}
+const smoothstep = (a, b, x) => {
+    const t = Math.min(1, Math.max(0, (x - a) / (b - a)));
+    return t * t * (3 - 2 * t);
+};
+const sat = (x) => Math.min(1, Math.max(0, x));
+/** `sky` of shaders/env/sky.wesl, in TS (for the SH projection). */
+export function skyRadiance(s, sun, d) {
+    const up = d[1];
+    const out = [0, 0, 0];
+    const ta = Math.pow(sat(up), 0.5);
+    const tb = sat(-up * 4);
+    const disk = smoothstep(Math.cos((s.sunAngle * Math.PI) / 180), 1, d[0] * sun[0] + d[1] * sun[1] + d[2] * sun[2]) * (up >= 0 ? 1 : 0);
+    for (let c = 0; c < 3; c++) {
+        const above = s.horizon[c] + (s.zenith[c] - s.horizon[c]) * ta;
+        const below = s.horizon[c] + (s.ground[c] - s.horizon[c]) * tb;
+        out[c] = (up >= 0 ? above : below) + s.sunDisk[c] * disk;
+    }
+    return out;
+}
+/**
+ * Projects `radiance` onto real SH up to l = 2 and convolves with the clamped cosine
+ * (Ramamoorthi & Hanrahan 2001), divided by π: `out` evaluated at n is the Lambert
+ * diffuse radiance for albedo 1. Coefficient order: Y00, Y1-1 (y), Y10 (z), Y11 (x), Y2-2 (xy),
+ * Y2-1 (yz), Y20, Y21 (xz), Y22 (x² − y²): `sh_irradiance` in draw.wesl reads the same.
+ */
+export function projectSh9(out, radiance) {
+    out.fill(0);
+    const nTheta = 64;
+    const nPhi = 128;
+    const A = [Math.PI, (2 * Math.PI) / 3, (2 * Math.PI) / 3, (2 * Math.PI) / 3, Math.PI / 4, Math.PI / 4, Math.PI / 4, Math.PI / 4, Math.PI / 4];
+    for (let i = 0; i < nTheta; i++) {
+        const theta = ((i + 0.5) / nTheta) * Math.PI;
+        const dOmega = (Math.PI / nTheta) * ((2 * Math.PI) / nPhi) * Math.sin(theta);
+        for (let j = 0; j < nPhi; j++) {
+            const phi = ((j + 0.5) / nPhi) * 2 * Math.PI;
+            const d = [Math.sin(theta) * Math.cos(phi), Math.cos(theta), Math.sin(theta) * Math.sin(phi)];
+            const L = radiance(d);
+            const [x, y, z] = d;
+            const Y = [0.282095, 0.488603 * y, 0.488603 * z, 0.488603 * x, 1.092548 * x * y, 1.092548 * y * z, 0.315392 * (3 * z * z - 1), 1.092548 * x * z, 0.546274 * (x * x - y * y)];
+            for (let k = 0; k < 9; k++)
+                for (let c = 0; c < 3; c++)
+                    out[k * 4 + c] += L[c] * Y[k] * dOmega;
+        }
+    }
+    for (let k = 0; k < 9; k++)
+        for (let c = 0; c < 3; c++)
+            out[k * 4 + c] *= A[k] / Math.PI;
+}
+//# sourceMappingURL=environment.js.map

package/dist/environment.js.map

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

package/dist/extract.d.ts

@@ -0,0 +1,74 @@
+import { type Component, type World } from '@yali-engine/core';
+import { type MeshStore } from './meshes.ts';
+/** What one extract left in linear memory (read by `SceneRenderer.upload`). */
+export interface ExtractedInstances {
+    /** Byte address of the records. GPU cull: the transform region, the static region `cap * 32` bytes later. CPU cull: interleaved 40-byte records grouped by draw slot (ADR-0059). */
+    readonly address: number;
+    /** Records the buffer holds (the static region's offset, in records). */
+    readonly cap: number;
+    /** Records written. */
+    readonly count: number;
+    /** True when a static record (colour, mesh, material) changed this frame (GPU cull only). */
+    readonly staticChanged: boolean;
+    /** Bumped when the buffer was reallocated: its static region must be uploaded whole. */
+    readonly epoch: number;
+    /** GPU cull: the f64 point the transform records are relative to (ADR-0075); the shaders subtract the camera's offset from it. */
+    readonly anchor: Float64Array;
+    /** GPU cull: transform ranges rewritten this frame, at `dirtyAt` as `[first, end)` record pairs; -1 = every record (ADR-0075). */
+    readonly dirty: number;
+    /** Byte address of the dirty ranges (after the count word). */
+    readonly dirtyAt: number;
+    /** Byte address of the per-mesh counts (GPU cull) or per-slot counts, `mesh * 8 + lod` (CPU cull). */
+    readonly countsAt: number;
+    /** Meshes counted. */
+    readonly meshes: number;
+    /** True when this frame was culled on the CPU (`yali_extract_culled`, ADR-0057). */
+    readonly culled: boolean;
+    /** The shadow cascades the CPU cull partitioned each slot by (0 = none; ADR-0073). */
+    readonly cascades: number;
+}
+/**
+ * Floats in the CPU cull's parameter block: six planes, lod scale, error px, min radius px,
+ * the cascade count, then five caster planes per cascade (ADR-0073).
+ */
+export declare const CULL_FLOATS = 88;
+/**
+ * The render Extract step (M2 increment 2): one core call writes every entity with
+ * `render.Mesh` and `GlobalTransform` into linear memory. By default the GPU culls
+ * (`yali_extract_instances`: records grouped by mesh, 32-byte transforms relative to an
+ * anchor near the camera (ADR-0075) plus 16-byte static records rewritten only on change,
+ * ADR-0055; only chunks that changed are rewritten, and the ranges are reported); with
+ * `runCulled` the CPU culls and picks LODs (`yali_extract_culled`, ADR-0057: interleaved
+ * records grouped by draw slot, with per-slot counts). Owns its linear-memory buffers and
+ * grows them when the scene does; allocation-free per frame after that.
+ */
+export declare class InstanceExtractor implements ExtractedInstances {
+    #private;
+    readonly world: World;
+    address: number;
+    cap: number;
+    count: number;
+    staticChanged: boolean;
+    epoch: number;
+    countsAt: number;
+    meshes: number;
+    culled: boolean;
+    /** The shadow cascades the last CPU cull partitioned by (ADR-0073). */
+    cascades: number;
+    readonly anchor: Float64Array<ArrayBuffer>;
+    dirty: number;
+    get dirtyAt(): number;
+    /** The CPU cull's parameter block (CULL_FLOATS f32), for `SceneRenderer.writeCullParams`. */
+    readonly cullAt: number;
+    constructor(world: World, Mesh: Component);
+    /** Extracts this frame's instances for the camera at `eye`, for meshes `0..meshes`, for the GPU to cull. Returns the record count. */
+    run(eye: Float64Array, meshes: number): number;
+    /**
+     * Extracts only the visible instances, culled and LOD-selected on the CPU (ADR-0057), with
+     * the parameters at `cullAt` (write them first: `SceneRenderer.writeCullParams`) and the
+     * meshes' bounds and LOD errors from `store`. Returns the record count.
+     */
+    runCulled(eye: Float64Array, store: MeshStore): number;
+    /** Frees the linear-memory buffers. */
+    dispose(): void;
+}

package/dist/extract.js

@@ -0,0 +1,194 @@
+import { registerTransforms } from '@yali-engine/core';
+import { MAX_LODS } from "./meshes.js";
+import { INSTANCE_BYTES } from "./scene.js";
+/**
+ * Floats in the CPU cull's parameter block: six planes, lod scale, error px, min radius px,
+ * the cascade count, then five caster planes per cascade (ADR-0073).
+ */
+export const CULL_FLOATS = 88;
+const MESH_WORDS = 16;
+/** Most dirty ranges the core reports before it says "every record". */
+const DIRTY_CAP = 64;
+/** The anchor moves when the camera is this far from it (metres): f32 offsets stay ~0.06 mm near the camera. */
+const REBASE_DISTANCE = 1000;
+/** The anchor snaps to this grid (metres). */
+const ANCHOR_GRID = 256;
+/**
+ * The render Extract step (M2 increment 2): one core call writes every entity with
+ * `render.Mesh` and `GlobalTransform` into linear memory. By default the GPU culls
+ * (`yali_extract_instances`: records grouped by mesh, 32-byte transforms relative to an
+ * anchor near the camera (ADR-0075) plus 16-byte static records rewritten only on change,
+ * ADR-0055; only chunks that changed are rewritten, and the ranges are reported); with
+ * `runCulled` the CPU culls and picks LODs (`yali_extract_culled`, ADR-0057: interleaved
+ * records grouped by draw slot, with per-slot counts). Owns its linear-memory buffers and
+ * grows them when the scene does; allocation-free per frame after that.
+ */
+export class InstanceExtractor {
+    world;
+    #query;
+    address = 0;
+    cap = 0;
+    count = 0;
+    staticChanged = false;
+    epoch = 0;
+    countsAt = 0;
+    #countsCap = 0;
+    meshes = 0;
+    culled = false;
+    /** The shadow cascades the last CPU cull partitioned by (ADR-0073). */
+    cascades = 0;
+    anchor = new Float64Array(3);
+    #anchored = false;
+    dirty = -1;
+    /** The count word, then DIRTY_CAP range pairs. */
+    #dirtyWordsAt;
+    get dirtyAt() {
+        return this.#dirtyWordsAt + 4;
+    }
+    /** One u32 the core sets when a static record changed. */
+    #changedAt;
+    /** The CPU cull's parameter block (CULL_FLOATS f32), for `SceneRenderer.writeCullParams`. */
+    cullAt;
+    #tableAt = 0;
+    #tableCap = 0;
+    #tableVersion = -1;
+    constructor(world, Mesh) {
+        this.world = world;
+        const { GlobalTransform } = registerTransforms(world);
+        this.#query = world.query({
+            with: [Mesh, GlobalTransform],
+            columns: [[GlobalTransform, 't'], [GlobalTransform, 'r'], [GlobalTransform, 's'], [Mesh, 'mesh'], [Mesh, 'material'], [Mesh, 'color'], [Mesh, 'skin']],
+        });
+        const x = world.core.exports;
+        this.#changedAt = x.yali_alloc(4);
+        this.#dirtyWordsAt = x.yali_alloc((1 + 2 * DIRTY_CAP) * 4);
+        this.cullAt = x.yali_alloc(CULL_FLOATS * 4);
+    }
+    /** Moves the anchor to the camera's grid cell when the camera is far from it (a rare full rewrite). */
+    #rebase(eye) {
+        const a = this.anchor;
+        const d = Math.hypot(eye[0] - a[0], eye[1] - a[1], eye[2] - a[2]);
+        if (this.#anchored && d <= REBASE_DISTANCE)
+            return;
+        for (let i = 0; i < 3; i++)
+            a[i] = Math.round(eye[i] / ANCHOR_GRID) * ANCHOR_GRID;
+        this.#anchored = true;
+    }
+    #ensureCounts(words) {
+        if (this.#countsCap >= words)
+            return;
+        const x = this.world.core.exports;
+        if (this.#countsCap > 0)
+            x.yali_dealloc(this.countsAt, this.#countsCap * 4);
+        this.#countsCap = nextPow2(words);
+        this.countsAt = x.yali_alloc(this.#countsCap * 4);
+    }
+    #grow(n) {
+        const x = this.world.core.exports;
+        if (this.cap > 0)
+            x.yali_dealloc(this.address, this.cap * INSTANCE_BYTES);
+        this.cap = nextPow2(n);
+        this.address = x.yali_alloc(this.cap * INSTANCE_BYTES);
+        this.epoch++;
+    }
+    /** Extracts this frame's instances for the camera at `eye`, for meshes `0..meshes`, for the GPU to cull. Returns the record count. */
+    run(eye, meshes) {
+        const w = this.world;
+        this.#ensureCounts(meshes);
+        this.#rebase(eye);
+        let n = this.#instances(meshes);
+        if (n > this.cap) {
+            this.#grow(n);
+            n = this.#instances(meshes);
+        }
+        w.core.heap.refresh();
+        const u32 = w.core.heap.u32;
+        this.staticChanged = u32[this.#changedAt >>> 2] !== 0;
+        const ranges = u32[this.#dirtyWordsAt >>> 2];
+        this.dirty = ranges === 0xffffffff ? -1 : ranges;
+        this.count = n;
+        this.meshes = meshes;
+        this.culled = false;
+        return n;
+    }
+    /**
+     * Extracts only the visible instances, culled and LOD-selected on the CPU (ADR-0057), with
+     * the parameters at `cullAt` (write them first: `SceneRenderer.writeCullParams`) and the
+     * meshes' bounds and LOD errors from `store`. Returns the record count.
+     */
+    runCulled(eye, store) {
+        const w = this.world;
+        const meshes = store.entries.length;
+        this.#syncTable(store);
+        w.core.heap.refresh();
+        this.cascades = Math.max(0, Math.min(3, w.core.heap.f32[(this.cullAt >>> 2) + 27] | 0));
+        this.#ensureCounts(meshes * MAX_LODS << this.cascades);
+        let n = this.#culled(eye, meshes);
+        if (n > this.cap) {
+            this.#grow(n);
+            n = this.#culled(eye, meshes);
+        }
+        w.core.heap.refresh();
+        this.staticChanged = true;
+        this.dirty = -1;
+        this.count = n;
+        this.meshes = meshes;
+        this.culled = true;
+        return n;
+    }
+    #instances(meshes) {
+        const w = this.world;
+        const a = this.anchor;
+        return w.check(w.core.exports.yali_extract_instances(w.handle, this.#query.id, a[0], a[1], a[2], this.address, this.cap, this.countsAt, meshes, this.#changedAt, this.#dirtyWordsAt, DIRTY_CAP));
+    }
+    #culled(eye, meshes) {
+        const w = this.world;
+        return w.check(w.core.exports.yali_extract_culled(w.handle, this.#query.id, eye[0], eye[1], eye[2], this.cullAt, this.#tableAt, meshes, this.address, this.cap, this.countsAt));
+    }
+    /** The mesh table the CPU cull reads (centre, radius, LOD count, LOD errors), rebuilt when the store changes. */
+    #syncTable(store) {
+        if (this.#tableVersion === store.version)
+            return;
+        const x = this.world.core.exports;
+        const meshes = store.entries.length;
+        if (this.#tableCap < meshes) {
+            if (this.#tableCap > 0)
+                x.yali_dealloc(this.#tableAt, this.#tableCap * MESH_WORDS * 4);
+            this.#tableCap = nextPow2(meshes);
+            this.#tableAt = x.yali_alloc(this.#tableCap * MESH_WORDS * 4);
+        }
+        this.world.core.heap.refresh();
+        const f32 = this.world.core.heap.f32;
+        const u32 = this.world.core.heap.u32;
+        for (let m = 0; m < meshes; m++) {
+            const e = store.entries[m];
+            const o = (this.#tableAt >>> 2) + m * MESH_WORDS;
+            f32[o] = e.center[0];
+            f32[o + 1] = e.center[1];
+            f32[o + 2] = e.center[2];
+            f32[o + 3] = e.radius;
+            u32[o + 4] = e.lods.length;
+            for (let l = 0; l < MAX_LODS; l++)
+                f32[o + 8 + l] = e.lods[l]?.error ?? 0;
+        }
+        this.#tableVersion = store.version;
+    }
+    /** Frees the linear-memory buffers. */
+    dispose() {
+        const x = this.world.core.exports;
+        if (this.cap > 0)
+            x.yali_dealloc(this.address, this.cap * INSTANCE_BYTES);
+        if (this.#countsCap > 0)
+            x.yali_dealloc(this.countsAt, this.#countsCap * 4);
+        if (this.#tableCap > 0)
+            x.yali_dealloc(this.#tableAt, this.#tableCap * MESH_WORDS * 4);
+        x.yali_dealloc(this.#changedAt, 4);
+        x.yali_dealloc(this.#dirtyWordsAt, (1 + 2 * DIRTY_CAP) * 4);
+        x.yali_dealloc(this.cullAt, CULL_FLOATS * 4);
+        this.cap = this.#countsCap = this.#tableCap = 0;
+    }
+}
+function nextPow2(n) {
+    return n <= 1 ? 1 : 2 ** Math.ceil(Math.log2(n));
+}
+//# sourceMappingURL=extract.js.map

package/dist/extract.js.map

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

package/dist/frame-graph.d.ts

@@ -0,0 +1,112 @@
+/** Context handed to every pass's `execute`. */
+export interface FrameContext {
+    readonly device: GPUDevice;
+    /** Current render size in pixels (the scene's targets). */
+    readonly width: number;
+    readonly height: number;
+    /** The output size: the canvas, larger than the render size when TAA upscales (ADR-0135); else the same. */
+    readonly outputWidth: number;
+    readonly outputHeight: number;
+    /** A graph texture's view (to sample what an earlier pass wrote). */
+    view(name: string): GPUTextureView;
+    /** A transient's texture (to copy from it; imported textures have only views). */
+    texture(name: string): GPUTexture;
+    /** Changes whenever transient textures are (re)allocated: rebuild bind groups that hold views. */
+    readonly generation: number;
+}
+interface PassBase {
+    /** Unique, conventionally `plugin.what`. */
+    readonly name: string;
+    /** Logical resources the pass reads (textures or buffers, by name). */
+    readonly reads?: readonly string[];
+    /** Logical resources the pass writes. */
+    readonly writes?: readonly string[];
+}
+/** A compute pass. */
+export interface ComputePassDef extends PassBase {
+    readonly kind: 'compute';
+    execute(pass: GPUComputePassEncoder, ctx: FrameContext): void;
+}
+/** A render pass. Its attachments are graph textures, so the graph builds the descriptor. */
+export interface RenderPassDef extends PassBase {
+    readonly kind: 'render';
+    /** The colour attachment; none for a depth-only pass (a shadow map). `load` keeps what an earlier pass drew. */
+    readonly color?: {
+        readonly target: string;
+        readonly clear: GPUColorDict;
+        readonly load?: boolean;
+    };
+    /**
+     * Reverse-Z (ADR-0008): clear depth to 0 and compare `greater`. Depth is discarded after
+     * the pass unless `store` (a shadow map another pass samples).
+     */
+    readonly depth?: {
+        readonly target: string;
+        readonly clear: number;
+        readonly store?: boolean;
+        readonly load?: boolean;
+    };
+    execute(pass: GPURenderPassEncoder, ctx: FrameContext): void;
+}
+/** Commands outside a pass (a texture copy): the frame's encoder itself. */
+export interface EncoderPassDef extends PassBase {
+    readonly kind: 'encoder';
+    execute(encoder: GPUCommandEncoder, ctx: FrameContext): void;
+}
+/** A pass of any kind. */
+export type PassDef = ComputePassDef | RenderPassDef | EncoderPassDef;
+/** A texture the graph allocates per frame size and may alias between passes. */
+export interface TransientTexture {
+    readonly format: GPUTextureFormat;
+    readonly usage: GPUTextureUsageFlags;
+    /** Fraction of its size (1 = full resolution). */
+    readonly scale?: number;
+    /** Sized from the output size instead of the render size: what runs after TAA's upscale (ADR-0135). */
+    readonly output?: boolean;
+}
+/** GPU timing hooks (the profiler implements them). */
+export interface PassTimer {
+    /** Timestamp writes for pass `index`, or undefined when timestamps are unavailable. */
+    timestampWrites(index: number): GPUComputePassTimestampWrites | undefined;
+}
+export declare class FrameGraph {
+    #private;
+    readonly device: GPUDevice;
+    /** Names of the compiled passes in execution order; pass `i` uses timestamp slot `i`.
+     *  Replaced (not mutated) on each compile, so a holder can detect a recompile by identity. */
+    passNames: readonly string[];
+    timer: PassTimer | null;
+    constructor(device: GPUDevice);
+    /** A texture owned outside the graph (the swapchain), fetched once per frame. */
+    importTexture(name: string, view: () => GPUTextureView): void;
+    /** A texture the graph allocates for the current size. */
+    transientTexture(name: string, desc: TransientTexture): void;
+    /** Adds a pass. Names are unique. */
+    addPass(def: PassDef): void;
+    /** The resource the frame exists to produce (usually `backbuffer`). */
+    setOutput(name: string): void;
+    /** Resizes transients (on the next `execute`); the output size defaults to the render size. */
+    resize(width: number, height: number, outputWidth?: number, outputHeight?: number): void;
+    /**
+     * Orders passes (a pass runs after every earlier-declared pass that writes what it
+     * reads), culls passes that don't contribute to the output, and allocates transients.
+     */
+    compile(): void;
+    /** Bytes the allocated transient textures hold (M2's render-target budget, `budgets.json`). */
+    get transientBytes(): number;
+    /** Records every compiled pass into `encoder`. */
+    execute(encoder: GPUCommandEncoder): void;
+    /** Transient textures currently allocated (for the dispose leak check). */
+    get liveTextures(): number;
+    /** Forces transients to be rebuilt on the next frame (the attachment-mismatch heal). */
+    invalidate(): void;
+    /** Destroys every transient texture. */
+    destroy(): void;
+    /** The compiled graph, for inspection (CLI, MCP, overlay). */
+    describe(): {
+        passes: string[];
+        culled: string[];
+        transients: string[];
+    };
+}
+export {};