@aardworx/wombat.rendering 0.7.2 → 0.8.0

package/dist/runtime/heapScene.d.ts

@@ -0,0 +1,61 @@
+import { Trafo3d, V3d, V4f } from "@aardworx/wombat.base";
+import type { aval } from "@aardworx/wombat.adaptive";
+import type { CanvasAttachment } from "../window/index.js";
+/**
+ * Geometry triple. Tightly-packed Float32 positions / normals (3
+ * floats per vertex) plus Uint32 indices. The heap-scene packer
+ * concatenates all draws' geometry into per-group slabs.
+ */
+export interface HeapGeometry {
+    readonly positions: Float32Array;
+    readonly normals: Float32Array;
+    readonly indices: Uint32Array;
+}
+export interface HeapDrawSpec {
+    readonly geo: HeapGeometry;
+    readonly modelTrafo: aval<Trafo3d> | Trafo3d;
+    readonly color: aval<V4f> | V4f;
+    /** Group key — selects which pipeline-state group this draw joins. */
+    readonly groupKey: string;
+}
+export interface HeapSceneStats {
+    readonly groups: number;
+    readonly totalDraws: number;
+    readonly globalsBytes: number;
+    drawBytes: number;
+    readonly geometryBytes: number;
+}
+export interface HeapScene {
+    /** Render one frame against the given globals. */
+    frame(viewProj: Trafo3d, lightLocation: V3d): void;
+    readonly stats: HeapSceneStats;
+    dispose(): void;
+}
+/**
+ * Per-group texture set. Bindless isn't standard WebGPU, so a group
+ * with sampled textures gets a distinct bind-group layout and is
+ * keyed separately from groups with no textures or different sets.
+ */
+export interface HeapTextureSet {
+    readonly texture: GPUTexture;
+    readonly textureView?: GPUTextureView;
+    readonly sampler: GPUSampler;
+}
+export interface BuildHeapSceneOptions {
+    /** WGSL fragment-stage source per group key — must declare `fs(in: VsOut) -> @location(0) vec4<f32>`. */
+    readonly fragmentShaders: ReadonlyMap<string, string>;
+    /**
+     * Per-group texture set. When present, the group's bind-group
+     * layout adds a `texture_2d<f32>` at binding 4 and a sampler at
+     * binding 5. The user's FS WGSL must declare them.
+     */
+    readonly texturesByGroupKey?: ReadonlyMap<string, HeapTextureSet>;
+}
+/**
+ * Build a multi-group heap-backed scene renderer. Buckets `draws` by
+ * `groupKey`, builds one pipeline + bind group + heap per bucket,
+ * subscribes per-RO avals so dirty marks propagate to per-slot
+ * `writeBuffer`s on the next `frame()`.
+ */
+export declare function buildHeapScene(device: GPUDevice, attach: CanvasAttachment, draws: readonly HeapDrawSpec[], opts: BuildHeapSceneOptions): HeapScene;
+//# sourceMappingURL=heapScene.d.ts.map

package/dist/runtime/heapScene.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heapScene.d.ts","sourceRoot":"","sources":["../../src/runtime/heapScene.ts"],"names":[],"mappings":"AA4CA,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAa,MAAM,uBAAuB,CAAC;AAErE,OAAO,KAAK,EAAE,IAAI,EAAe,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AA4G3D;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAI,YAAY,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAI,WAAW,CAAC;CACjC;AAoLD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IAChC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,SAAS;IACxB,kDAAkD;IAClD,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,GAAG,GAAG,IAAI,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,cAAc,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;CAC9B;AAED,MAAM,WAAW,qBAAqB;IACpC,yGAAyG;IACzG,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtD;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACnE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,IAAI,EAAE,qBAAqB,GAC1B,SAAS,CA6GX"}

package/dist/runtime/heapScene.js

@@ -0,0 +1,354 @@
+// heapScene — multi-group heap-everything render path.
+//
+// Public-API extraction of the experimental heap-demo (commits in
+// the `experimental/heap-arch` branch document the design). One
+// shared GPURenderPipeline + GPUBindGroup per pipeline-state group,
+// per-draw uniforms in a storage buffer, vertex pulling from packed
+// position / normal slabs, indexed draws via a shared index buffer
+// and `firstInstance` routing into the heap.
+//
+// Per-frame uploads:
+//   - Globals (one UBO per group): viewProj + lightLocation. ~80 B.
+//     Independent of draw count.
+//   - DrawHeader (one storage buffer per group): only slots whose
+//     `aval<Trafo3d>` or `aval<V4f>` were marked since last frame
+//     are re-uploaded — 160 B per dirty slot.
+//
+// Geometry is uploaded ONCE at construction (positions + normals +
+// indices, packed across all draws in a group).
+//
+// The user supplies a fragment-shader body per group key. The vertex
+// stage is provided by this module and reads from a fixed layout:
+//
+//   @group(0) @binding(0) var<uniform>             globals:   Globals;
+//   @group(0) @binding(1) var<storage, read>       draws:     array<DrawHeader>;
+//   @group(0) @binding(2) var<storage, read>       positions: array<f32>;
+//   @group(0) @binding(3) var<storage, read>       normals:   array<f32>;
+//
+//   struct VsOut {
+//     @builtin(position) clipPos:  vec4<f32>,
+//     @location(0)       worldPos: vec3<f32>,
+//     @location(1)       normal:   vec3<f32>,
+//     @location(2)       color:    vec4<f32>,
+//     @location(3)       lightLoc: vec3<f32>,
+//   };
+//
+// User WGSL must declare `@fragment fn fs(in: VsOut) -> @location(0) vec4<f32>`.
+//
+// Per-group texture sets. WebGPU 1.0 has no bindless, so texture-set
+// is a wedge in the group key: groups with different texture sets
+// can't share a bind group. Pass a `textures: { texture, sampler }`
+// per groupKey via `BuildHeapSceneOptions.texturesByGroupKey`. The
+// package adds the texture (binding 4) + sampler (binding 5) to that
+// group's bind-group layout; the user's FS WGSL declares them.
+import { Trafo3d, V3d, V4f } from "@aardworx/wombat.base";
+import { AVal, addMarkingCallback } from "@aardworx/wombat.adaptive";
+// ---------------------------------------------------------------------------
+// Layouts
+// ---------------------------------------------------------------------------
+const GLOBALS_BYTES = 64 + 16; // mat4 + vec4
+const GLOBALS_FLOATS = GLOBALS_BYTES / 4;
+const DRAW_HEADER_BYTES = 64 * 2 + 16 + 16; // 2 mat4 + vec4 + (u32 + 3*pad)
+const DRAW_HEADER_FLOATS = DRAW_HEADER_BYTES / 4;
+function packMat44(m, dst, off) {
+    // M44d._data is the row-major Float64Array; not part of the public
+    // type surface. toArray() round-trips through a fresh number[] which
+    // we copy into the f32 staging buffer below.
+    const r = m.toArray();
+    for (let i = 0; i < 16; i++)
+        dst[off + i] = r[i];
+}
+function packGlobals(viewProj, lightLocation, dst) {
+    packMat44(viewProj.forward, dst, 0);
+    dst[16] = lightLocation.x;
+    dst[17] = lightLocation.y;
+    dst[18] = lightLocation.z;
+    dst[19] = 0;
+}
+function packDrawHeader(modelTrafo, color, vertexBase, dst, drawIndex) {
+    const off = drawIndex * DRAW_HEADER_FLOATS;
+    packMat44(modelTrafo.forward, dst, off + 0);
+    packMat44(modelTrafo.backward, dst, off + 16);
+    dst[off + 32] = color.x;
+    dst[off + 33] = color.y;
+    dst[off + 34] = color.z;
+    dst[off + 35] = color.w;
+    new Uint32Array(dst.buffer, dst.byteOffset, dst.length)[off + 36] = vertexBase;
+}
+// ---------------------------------------------------------------------------
+// Shared WGSL prelude (struct + bindings + VS)
+// ---------------------------------------------------------------------------
+const SHADER_PRELUDE = /* wgsl */ `
+struct Globals {
+  viewProj:      mat4x4<f32>,
+  lightLocation: vec4<f32>,
+};
+struct DrawHeader {
+  modelTrafo:    mat4x4<f32>,
+  modelTrafoInv: mat4x4<f32>,
+  color:         vec4<f32>,
+  vertexBase:    u32,
+  _pad0: u32, _pad1: u32, _pad2: u32,
+};
+@group(0) @binding(0) var<uniform>             globals:   Globals;
+@group(0) @binding(1) var<storage, read>       draws:     array<DrawHeader>;
+@group(0) @binding(2) var<storage, read>       positions: array<f32>;
+@group(0) @binding(3) var<storage, read>       normals:   array<f32>;
+
+struct VsOut {
+  @builtin(position) clipPos:  vec4<f32>,
+  @location(0)       worldPos: vec3<f32>,
+  @location(1)       normal:   vec3<f32>,
+  @location(2)       color:    vec4<f32>,
+  @location(3)       lightLoc: vec3<f32>,
+};
+
+fn fetchVec3(buf: ptr<storage, array<f32>, read>, base: u32) -> vec3<f32> {
+  return vec3<f32>((*buf)[base + 0u], (*buf)[base + 1u], (*buf)[base + 2u]);
+}
+
+@vertex
+fn vs(@builtin(vertex_index) vid: u32, @builtin(instance_index) drawIdx: u32) -> VsOut {
+  let d = draws[drawIdx];
+  let base = (d.vertexBase + vid) * 3u;
+  let pos = fetchVec3(&positions, base);
+  let nor = fetchVec3(&normals,   base);
+  // wombat.shader convention: matrices uploaded row-major; WGSL reads
+  // them as col-major = transposed. v * M is the row-vec dual of
+  // M.mul(v) (= M*v math).
+  let wp = vec4<f32>(pos, 1.0) * d.modelTrafo;
+  let n  = (vec4<f32>(nor, 0.0) * d.modelTrafo).xyz;
+  var out: VsOut;
+  out.clipPos  = wp * globals.viewProj;
+  out.worldPos = wp.xyz;
+  out.normal   = n;
+  out.color    = d.color;
+  out.lightLoc = globals.lightLocation.xyz;
+  return out;
+}
+`;
+function packGeometry(device, geos, label) {
+    let totalVerts = 0, totalIndices = 0;
+    for (const g of geos) {
+        totalVerts += g.positions.length / 3;
+        totalIndices += g.indices.length;
+    }
+    const positions = new Float32Array(totalVerts * 3);
+    const normals = new Float32Array(totalVerts * 3);
+    const indices = new Uint32Array(totalIndices);
+    const entries = [];
+    let vOff = 0, iOff = 0;
+    for (const g of geos) {
+        const vCount = g.positions.length / 3;
+        positions.set(g.positions, vOff * 3);
+        normals.set(g.normals, vOff * 3);
+        indices.set(g.indices, iOff);
+        entries.push({ vertexBase: vOff, indexCount: g.indices.length, firstIndex: iOff });
+        vOff += vCount;
+        iOff += g.indices.length;
+    }
+    const mk = (data, usage, lbl) => {
+        const buf = device.createBuffer({
+            size: alignUp(data.byteLength, 4),
+            usage: usage | GPUBufferUsage.COPY_DST,
+            label: lbl,
+        });
+        device.queue.writeBuffer(buf, 0, data.buffer, data.byteOffset, data.byteLength);
+        return buf;
+    };
+    return {
+        positionsBuf: mk(positions, GPUBufferUsage.STORAGE, `${label}/pos`),
+        normalsBuf: mk(normals, GPUBufferUsage.STORAGE, `${label}/nor`),
+        indexBuf: mk(indices, GPUBufferUsage.INDEX, `${label}/idx`),
+        entries,
+        bytes: positions.byteLength + normals.byteLength + indices.byteLength,
+    };
+}
+function alignUp(n, a) { return (n + a - 1) & ~(a - 1); }
+function asAval(v) {
+    return (typeof v === "object" && v !== null && typeof v.getValue === "function")
+        ? v
+        : AVal.constant(v);
+}
+function buildGroup(device, attach, key, fragmentWgsl, textureSet, draws, modelTrafos, colors) {
+    const sig = attach.signature;
+    const colorAttachmentName = sig.colorNames[0];
+    if (colorAttachmentName === undefined) {
+        throw new Error("buildHeapScene: framebuffer signature has no color attachment");
+    }
+    const colorFormat = sig.colors.tryFind(colorAttachmentName);
+    const depthFormat = sig.depthStencil?.format;
+    const memberIndices = draws.map(d => d.sourceIndex);
+    const myTrafos = memberIndices.map(i => modelTrafos[i]);
+    const myColors = memberIndices.map(i => colors[i]);
+    const packed = packGeometry(device, draws.map(d => d.spec.geo), `heapScene/${key}`);
+    const globals = device.createBuffer({
+        size: alignUp(GLOBALS_BYTES, 16),
+        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        label: `heapScene/${key}/globals`,
+    });
+    const globalsStaging = new Float32Array(GLOBALS_FLOATS);
+    const heapBytes = DRAW_HEADER_BYTES * draws.length;
+    const drawHeap = device.createBuffer({
+        size: alignUp(heapBytes, 16),
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        label: `heapScene/${key}/draws`,
+    });
+    const drawStaging = new Float32Array(DRAW_HEADER_FLOATS * draws.length);
+    for (let i = 0; i < draws.length; i++) {
+        packDrawHeader(myTrafos[i].force( /* allow-force */), myColors[i].force( /* allow-force */), packed.entries[i].vertexBase, drawStaging, i);
+    }
+    device.queue.writeBuffer(drawHeap, 0, drawStaging.buffer, drawStaging.byteOffset, heapBytes);
+    const dirty = new Set();
+    const subs = [];
+    for (let i = 0; i < draws.length; i++) {
+        subs.push(addMarkingCallback(myTrafos[i], () => dirty.add(i)));
+        subs.push(addMarkingCallback(myColors[i], () => dirty.add(i)));
+    }
+    const module = device.createShaderModule({
+        code: SHADER_PRELUDE + fragmentWgsl,
+        label: `heapScene/${key}/shader`,
+    });
+    const bindLayoutEntries = [
+        { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "uniform" } },
+        { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+        { binding: 2, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+        { binding: 3, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+    ];
+    if (textureSet !== undefined) {
+        bindLayoutEntries.push({ binding: 4, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } }, { binding: 5, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" } });
+    }
+    const bindGroupLayout = device.createBindGroupLayout({
+        label: `heapScene/${key}/bgl`,
+        entries: bindLayoutEntries,
+    });
+    const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout] });
+    const pipeline = device.createRenderPipeline({
+        label: `heapScene/${key}/pipeline`,
+        layout: pipelineLayout,
+        vertex: { module, entryPoint: "vs", buffers: [] },
+        fragment: { module, entryPoint: "fs", targets: [{ format: colorFormat }] },
+        primitive: { topology: "triangle-list", cullMode: "back", frontFace: "ccw" },
+        ...(depthFormat !== undefined
+            ? { depthStencil: { format: depthFormat, depthWriteEnabled: true, depthCompare: "less" } }
+            : {}),
+    });
+    const bindEntries = [
+        { binding: 0, resource: { buffer: globals } },
+        { binding: 1, resource: { buffer: drawHeap } },
+        { binding: 2, resource: { buffer: packed.positionsBuf } },
+        { binding: 3, resource: { buffer: packed.normalsBuf } },
+    ];
+    if (textureSet !== undefined) {
+        bindEntries.push({ binding: 4, resource: textureSet.textureView ?? textureSet.texture.createView() }, { binding: 5, resource: textureSet.sampler });
+    }
+    const bindGroup = device.createBindGroup({
+        label: `heapScene/${key}/bg`,
+        layout: bindGroupLayout,
+        entries: bindEntries,
+    });
+    return {
+        key, pipeline, bindGroup, globals, globalsStaging, drawHeap, drawStaging,
+        packed, trafos: myTrafos, colors: myColors, dirty, subs,
+    };
+}
+/**
+ * Build a multi-group heap-backed scene renderer. Buckets `draws` by
+ * `groupKey`, builds one pipeline + bind group + heap per bucket,
+ * subscribes per-RO avals so dirty marks propagate to per-slot
+ * `writeBuffer`s on the next `frame()`.
+ */
+export function buildHeapScene(device, attach, draws, opts) {
+    const modelTrafos = draws.map(d => asAval(d.modelTrafo));
+    const colors = draws.map(d => asAval(d.color));
+    // Bucket by group key.
+    const buckets = new Map();
+    for (let i = 0; i < draws.length; i++) {
+        const d = draws[i];
+        let bucket = buckets.get(d.groupKey);
+        if (bucket === undefined) {
+            bucket = [];
+            buckets.set(d.groupKey, bucket);
+        }
+        bucket.push({ spec: d, sourceIndex: i });
+    }
+    const groups = [];
+    for (const [key, members] of buckets) {
+        const fs = opts.fragmentShaders.get(key);
+        if (fs === undefined) {
+            throw new Error(`buildHeapScene: no fragment shader supplied for groupKey '${key}'`);
+        }
+        const textureSet = opts.texturesByGroupKey?.get(key);
+        groups.push(buildGroup(device, attach, key, fs, textureSet, members, modelTrafos, colors));
+    }
+    const stats = {
+        groups: groups.length,
+        totalDraws: draws.length,
+        globalsBytes: GLOBALS_BYTES * groups.length,
+        drawBytes: 0,
+        geometryBytes: groups.reduce((acc, g) => acc + g.packed.bytes, 0),
+    };
+    function frame(viewProj, lightLocation) {
+        const fb = attach.framebuffer.force( /* allow-force */);
+        const colorAttachmentName = attach.signature.colorNames[0];
+        const colorView = fb.colors.tryFind(colorAttachmentName);
+        const depthFormat = attach.signature.depthStencil?.format;
+        const depthView = fb.depthStencil;
+        let totalDirtyBytes = 0;
+        const enc = device.createCommandEncoder({ label: "heapScene: encoder" });
+        let firstPass = true;
+        for (const g of groups) {
+            packGlobals(viewProj, lightLocation, g.globalsStaging);
+            device.queue.writeBuffer(g.globals, 0, g.globalsStaging.buffer, g.globalsStaging.byteOffset, GLOBALS_BYTES);
+            if (g.dirty.size > 0) {
+                for (const i of g.dirty) {
+                    packDrawHeader(g.trafos[i].force( /* allow-force */), g.colors[i].force( /* allow-force */), g.packed.entries[i].vertexBase, g.drawStaging, i);
+                    const byteOff = i * DRAW_HEADER_BYTES;
+                    device.queue.writeBuffer(g.drawHeap, byteOff, g.drawStaging.buffer, g.drawStaging.byteOffset + byteOff, DRAW_HEADER_BYTES);
+                    totalDirtyBytes += DRAW_HEADER_BYTES;
+                }
+                g.dirty.clear();
+            }
+            const pass = enc.beginRenderPass({
+                colorAttachments: [{
+                        view: colorView,
+                        clearValue: { r: 0.07, g: 0.07, b: 0.08, a: 1.0 },
+                        loadOp: firstPass ? "clear" : "load",
+                        storeOp: "store",
+                    }],
+                ...(depthView !== undefined && depthFormat !== undefined ? {
+                    depthStencilAttachment: {
+                        view: depthView,
+                        depthClearValue: 1.0,
+                        depthLoadOp: firstPass ? "clear" : "load",
+                        depthStoreOp: "store",
+                    },
+                } : {}),
+            });
+            pass.setPipeline(g.pipeline);
+            pass.setBindGroup(0, g.bindGroup);
+            pass.setIndexBuffer(g.packed.indexBuf, "uint32");
+            for (let i = 0; i < g.packed.entries.length; i++) {
+                const e = g.packed.entries[i];
+                pass.drawIndexed(e.indexCount, 1, e.firstIndex, 0, i);
+            }
+            pass.end();
+            firstPass = false;
+        }
+        stats.drawBytes = totalDirtyBytes;
+        device.queue.submit([enc.finish()]);
+    }
+    function dispose() {
+        for (const g of groups) {
+            for (const s of g.subs)
+                s.dispose();
+            g.globals.destroy();
+            g.drawHeap.destroy();
+            g.packed.positionsBuf.destroy();
+            g.packed.normalsBuf.destroy();
+            g.packed.indexBuf.destroy();
+        }
+    }
+    return { frame, stats, dispose };
+}
+//# sourceMappingURL=heapScene.js.map

package/dist/runtime/heapScene.js.map

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

package/dist/runtime/index.d.ts

@@ -3,4 +3,5 @@ export { compileRenderTask, type RuntimeContext, } from "./renderTask.js";
 export { copy } from "./copy.js";
 export { renderTo, type RenderToOptions, type RenderToResult, } from "./renderTo.js";
 export { ScenePass, type WalkerStats, } from "./scenePass.js";
+export { buildHeapScene, type HeapScene, type HeapSceneStats, type HeapDrawSpec, type HeapGeometry, type HeapTextureSet, type BuildHeapSceneOptions, } from "./heapScene.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,OAAO,EACP,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EACL,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,SAAS,EACT,KAAK,WAAW,GACjB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,OAAO,EACP,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EACL,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,SAAS,EACT,KAAK,WAAW,GACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,cAAc,EACd,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,qBAAqB,GAC3B,MAAM,gBAAgB,CAAC"}

package/dist/runtime/index.js

@@ -4,4 +4,5 @@ export { compileRenderTask, } from "./renderTask.js";
 export { copy } from "./copy.js";
 export { renderTo, } from "./renderTo.js";
 export { ScenePass, } from "./scenePass.js";
+export { buildHeapScene, } from "./heapScene.js";
 //# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,oDAAoD;AAEpD,OAAO,EACL,OAAO,GAER,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,GAElB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EACL,QAAQ,GAGT,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,SAAS,GAEV,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,oDAAoD;AAEpD,OAAO,EACL,OAAO,GAER,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,GAElB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EACL,QAAQ,GAGT,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,SAAS,GAEV,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,cAAc,GAOf,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aardworx/wombat.rendering",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "WebGPU rendering layer for the Wombat TypeScript stack \u2014 RenderObject/RenderTask/runtime + window glue, port of Aardvark.Rendering's lower layers on top of WebGPU and wombat.shader.",
   "license": "MIT",
   "author": "krauthaufen",

package/src/runtime/heapScene.ts

@@ -0,0 +1,510 @@
+// heapScene — multi-group heap-everything render path.
+//
+// Public-API extraction of the experimental heap-demo (commits in
+// the `experimental/heap-arch` branch document the design). One
+// shared GPURenderPipeline + GPUBindGroup per pipeline-state group,
+// per-draw uniforms in a storage buffer, vertex pulling from packed
+// position / normal slabs, indexed draws via a shared index buffer
+// and `firstInstance` routing into the heap.
+//
+// Per-frame uploads:
+//   - Globals (one UBO per group): viewProj + lightLocation. ~80 B.
+//     Independent of draw count.
+//   - DrawHeader (one storage buffer per group): only slots whose
+//     `aval<Trafo3d>` or `aval<V4f>` were marked since last frame
+//     are re-uploaded — 160 B per dirty slot.
+//
+// Geometry is uploaded ONCE at construction (positions + normals +
+// indices, packed across all draws in a group).
+//
+// The user supplies a fragment-shader body per group key. The vertex
+// stage is provided by this module and reads from a fixed layout:
+//
+//   @group(0) @binding(0) var<uniform>             globals:   Globals;
+//   @group(0) @binding(1) var<storage, read>       draws:     array<DrawHeader>;
+//   @group(0) @binding(2) var<storage, read>       positions: array<f32>;
+//   @group(0) @binding(3) var<storage, read>       normals:   array<f32>;
+//
+//   struct VsOut {
+//     @builtin(position) clipPos:  vec4<f32>,
+//     @location(0)       worldPos: vec3<f32>,
+//     @location(1)       normal:   vec3<f32>,
+//     @location(2)       color:    vec4<f32>,
+//     @location(3)       lightLoc: vec3<f32>,
+//   };
+//
+// User WGSL must declare `@fragment fn fs(in: VsOut) -> @location(0) vec4<f32>`.
+//
+// Per-group texture sets. WebGPU 1.0 has no bindless, so texture-set
+// is a wedge in the group key: groups with different texture sets
+// can't share a bind group. Pass a `textures: { texture, sampler }`
+// per groupKey via `BuildHeapSceneOptions.texturesByGroupKey`. The
+// package adds the texture (binding 4) + sampler (binding 5) to that
+// group's bind-group layout; the user's FS WGSL declares them.
+
+import { Trafo3d, V3d, V4f, type M44d } from "@aardworx/wombat.base";
+import { AVal, addMarkingCallback } from "@aardworx/wombat.adaptive";
+import type { aval, IDisposable } from "@aardworx/wombat.adaptive";
+import type { CanvasAttachment } from "../window/index.js";
+
+// ---------------------------------------------------------------------------
+// Layouts
+// ---------------------------------------------------------------------------
+
+const GLOBALS_BYTES = 64 + 16;                                    // mat4 + vec4
+const GLOBALS_FLOATS = GLOBALS_BYTES / 4;
+const DRAW_HEADER_BYTES = 64 * 2 + 16 + 16;                       // 2 mat4 + vec4 + (u32 + 3*pad)
+const DRAW_HEADER_FLOATS = DRAW_HEADER_BYTES / 4;
+
+function packMat44(m: M44d, dst: Float32Array, off: number): void {
+  // M44d._data is the row-major Float64Array; not part of the public
+  // type surface. toArray() round-trips through a fresh number[] which
+  // we copy into the f32 staging buffer below.
+  const r = m.toArray();
+  for (let i = 0; i < 16; i++) dst[off + i] = r[i]!;
+}
+
+function packGlobals(viewProj: Trafo3d, lightLocation: V3d, dst: Float32Array): void {
+  packMat44(viewProj.forward, dst, 0);
+  dst[16] = lightLocation.x as number;
+  dst[17] = lightLocation.y as number;
+  dst[18] = lightLocation.z as number;
+  dst[19] = 0;
+}
+
+function packDrawHeader(
+  modelTrafo: Trafo3d,
+  color: V4f,
+  vertexBase: number,
+  dst: Float32Array,
+  drawIndex: number,
+): void {
+  const off = drawIndex * DRAW_HEADER_FLOATS;
+  packMat44(modelTrafo.forward,  dst, off +  0);
+  packMat44(modelTrafo.backward, dst, off + 16);
+  dst[off + 32] = color.x; dst[off + 33] = color.y;
+  dst[off + 34] = color.z; dst[off + 35] = color.w;
+  new Uint32Array(dst.buffer, dst.byteOffset, dst.length)[off + 36] = vertexBase;
+}
+
+// ---------------------------------------------------------------------------
+// Shared WGSL prelude (struct + bindings + VS)
+// ---------------------------------------------------------------------------
+
+const SHADER_PRELUDE = /* wgsl */`
+struct Globals {
+  viewProj:      mat4x4<f32>,
+  lightLocation: vec4<f32>,
+};
+struct DrawHeader {
+  modelTrafo:    mat4x4<f32>,
+  modelTrafoInv: mat4x4<f32>,
+  color:         vec4<f32>,
+  vertexBase:    u32,
+  _pad0: u32, _pad1: u32, _pad2: u32,
+};
+@group(0) @binding(0) var<uniform>             globals:   Globals;
+@group(0) @binding(1) var<storage, read>       draws:     array<DrawHeader>;
+@group(0) @binding(2) var<storage, read>       positions: array<f32>;
+@group(0) @binding(3) var<storage, read>       normals:   array<f32>;
+
+struct VsOut {
+  @builtin(position) clipPos:  vec4<f32>,
+  @location(0)       worldPos: vec3<f32>,
+  @location(1)       normal:   vec3<f32>,
+  @location(2)       color:    vec4<f32>,
+  @location(3)       lightLoc: vec3<f32>,
+};
+
+fn fetchVec3(buf: ptr<storage, array<f32>, read>, base: u32) -> vec3<f32> {
+  return vec3<f32>((*buf)[base + 0u], (*buf)[base + 1u], (*buf)[base + 2u]);
+}
+
+@vertex
+fn vs(@builtin(vertex_index) vid: u32, @builtin(instance_index) drawIdx: u32) -> VsOut {
+  let d = draws[drawIdx];
+  let base = (d.vertexBase + vid) * 3u;
+  let pos = fetchVec3(&positions, base);
+  let nor = fetchVec3(&normals,   base);
+  // wombat.shader convention: matrices uploaded row-major; WGSL reads
+  // them as col-major = transposed. v * M is the row-vec dual of
+  // M.mul(v) (= M*v math).
+  let wp = vec4<f32>(pos, 1.0) * d.modelTrafo;
+  let n  = (vec4<f32>(nor, 0.0) * d.modelTrafo).xyz;
+  var out: VsOut;
+  out.clipPos  = wp * globals.viewProj;
+  out.worldPos = wp.xyz;
+  out.normal   = n;
+  out.color    = d.color;
+  out.lightLoc = globals.lightLocation.xyz;
+  return out;
+}
+`;
+
+// ---------------------------------------------------------------------------
+// Geometry packing
+// ---------------------------------------------------------------------------
+
+interface PackedGeometry {
+  readonly positionsBuf: GPUBuffer;
+  readonly normalsBuf:   GPUBuffer;
+  readonly indexBuf:     GPUBuffer;
+  readonly entries:      ReadonlyArray<{ vertexBase: number; indexCount: number; firstIndex: number }>;
+  readonly bytes:        number;
+}
+
+/**
+ * Geometry triple. Tightly-packed Float32 positions / normals (3
+ * floats per vertex) plus Uint32 indices. The heap-scene packer
+ * concatenates all draws' geometry into per-group slabs.
+ */
+export interface HeapGeometry {
+  readonly positions: Float32Array;
+  readonly normals:   Float32Array;
+  readonly indices:   Uint32Array;
+}
+
+function packGeometry(device: GPUDevice, geos: readonly HeapGeometry[], label: string): PackedGeometry {
+  let totalVerts = 0, totalIndices = 0;
+  for (const g of geos) {
+    totalVerts   += g.positions.length / 3;
+    totalIndices += g.indices.length;
+  }
+  const positions = new Float32Array(totalVerts * 3);
+  const normals   = new Float32Array(totalVerts * 3);
+  const indices   = new Uint32Array(totalIndices);
+  const entries: { vertexBase: number; indexCount: number; firstIndex: number }[] = [];
+  let vOff = 0, iOff = 0;
+  for (const g of geos) {
+    const vCount = g.positions.length / 3;
+    positions.set(g.positions, vOff * 3);
+    normals.set(g.normals,     vOff * 3);
+    indices.set(g.indices, iOff);
+    entries.push({ vertexBase: vOff, indexCount: g.indices.length, firstIndex: iOff });
+    vOff += vCount;
+    iOff += g.indices.length;
+  }
+  const mk = (data: ArrayBufferView, usage: GPUBufferUsageFlags, lbl: string): GPUBuffer => {
+    const buf = device.createBuffer({
+      size: alignUp(data.byteLength, 4),
+      usage: usage | GPUBufferUsage.COPY_DST,
+      label: lbl,
+    });
+    device.queue.writeBuffer(buf, 0, data.buffer, data.byteOffset, data.byteLength);
+    return buf;
+  };
+  return {
+    positionsBuf: mk(positions, GPUBufferUsage.STORAGE, `${label}/pos`),
+    normalsBuf:   mk(normals,   GPUBufferUsage.STORAGE, `${label}/nor`),
+    indexBuf:     mk(indices,   GPUBufferUsage.INDEX,   `${label}/idx`),
+    entries,
+    bytes: positions.byteLength + normals.byteLength + indices.byteLength,
+  };
+}
+
+function alignUp(n: number, a: number): number { return (n + a - 1) & ~(a - 1); }
+
+function asAval<T>(v: aval<T> | T): aval<T> {
+  return (typeof v === "object" && v !== null && typeof (v as { getValue?: unknown }).getValue === "function")
+    ? (v as aval<T>)
+    : AVal.constant(v as T);
+}
+
+// ---------------------------------------------------------------------------
+// Per-group internal state
+// ---------------------------------------------------------------------------
+
+interface Group {
+  readonly key: string;
+  readonly pipeline: GPURenderPipeline;
+  readonly bindGroup: GPUBindGroup;
+  readonly globals: GPUBuffer;
+  readonly globalsStaging: Float32Array;
+  readonly drawHeap: GPUBuffer;
+  readonly drawStaging: Float32Array;
+  readonly packed: PackedGeometry;
+  readonly trafos: aval<Trafo3d>[];
+  readonly colors: aval<V4f>[];
+  readonly dirty: Set<number>;
+  readonly subs: IDisposable[];
+}
+
+function buildGroup(
+  device: GPUDevice,
+  attach: CanvasAttachment,
+  key: string,
+  fragmentWgsl: string,
+  textureSet: HeapTextureSet | undefined,
+  draws: readonly { spec: HeapDrawSpec; sourceIndex: number }[],
+  modelTrafos: aval<Trafo3d>[],
+  colors: aval<V4f>[],
+): Group {
+  const sig = attach.signature;
+  const colorAttachmentName = sig.colorNames[0];
+  if (colorAttachmentName === undefined) {
+    throw new Error("buildHeapScene: framebuffer signature has no color attachment");
+  }
+  const colorFormat = sig.colors.tryFind(colorAttachmentName)!;
+  const depthFormat = sig.depthStencil?.format;
+
+  const memberIndices = draws.map(d => d.sourceIndex);
+  const myTrafos = memberIndices.map(i => modelTrafos[i]!);
+  const myColors = memberIndices.map(i => colors[i]!);
+
+  const packed = packGeometry(device, draws.map(d => d.spec.geo), `heapScene/${key}`);
+
+  const globals = device.createBuffer({
+    size: alignUp(GLOBALS_BYTES, 16),
+    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+    label: `heapScene/${key}/globals`,
+  });
+  const globalsStaging = new Float32Array(GLOBALS_FLOATS);
+
+  const heapBytes = DRAW_HEADER_BYTES * draws.length;
+  const drawHeap = device.createBuffer({
+    size: alignUp(heapBytes, 16),
+    usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+    label: `heapScene/${key}/draws`,
+  });
+  const drawStaging = new Float32Array(DRAW_HEADER_FLOATS * draws.length);
+  for (let i = 0; i < draws.length; i++) {
+    packDrawHeader(
+      myTrafos[i]!.force(/* allow-force */),
+      myColors[i]!.force(/* allow-force */),
+      packed.entries[i]!.vertexBase, drawStaging, i,
+    );
+  }
+  device.queue.writeBuffer(drawHeap, 0, drawStaging.buffer, drawStaging.byteOffset, heapBytes);
+
+  const dirty = new Set<number>();
+  const subs: IDisposable[] = [];
+  for (let i = 0; i < draws.length; i++) {
+    subs.push(addMarkingCallback(myTrafos[i] as never, () => dirty.add(i)));
+    subs.push(addMarkingCallback(myColors[i] as never, () => dirty.add(i)));
+  }
+
+  const module = device.createShaderModule({
+    code: SHADER_PRELUDE + fragmentWgsl,
+    label: `heapScene/${key}/shader`,
+  });
+  const bindLayoutEntries: GPUBindGroupLayoutEntry[] = [
+    { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "uniform" } },
+    { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+    { binding: 2, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+    { binding: 3, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+  ];
+  if (textureSet !== undefined) {
+    bindLayoutEntries.push(
+      { binding: 4, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+      { binding: 5, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" } },
+    );
+  }
+  const bindGroupLayout = device.createBindGroupLayout({
+    label: `heapScene/${key}/bgl`,
+    entries: bindLayoutEntries,
+  });
+  const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout] });
+  const pipeline = device.createRenderPipeline({
+    label: `heapScene/${key}/pipeline`,
+    layout: pipelineLayout,
+    vertex:   { module, entryPoint: "vs", buffers: [] },
+    fragment: { module, entryPoint: "fs", targets: [{ format: colorFormat }] },
+    primitive: { topology: "triangle-list", cullMode: "back", frontFace: "ccw" },
+    ...(depthFormat !== undefined
+      ? { depthStencil: { format: depthFormat, depthWriteEnabled: true, depthCompare: "less" as GPUCompareFunction } }
+      : {}),
+  });
+  const bindEntries: GPUBindGroupEntry[] = [
+    { binding: 0, resource: { buffer: globals } },
+    { binding: 1, resource: { buffer: drawHeap } },
+    { binding: 2, resource: { buffer: packed.positionsBuf } },
+    { binding: 3, resource: { buffer: packed.normalsBuf } },
+  ];
+  if (textureSet !== undefined) {
+    bindEntries.push(
+      { binding: 4, resource: textureSet.textureView ?? textureSet.texture.createView() },
+      { binding: 5, resource: textureSet.sampler },
+    );
+  }
+  const bindGroup = device.createBindGroup({
+    label: `heapScene/${key}/bg`,
+    layout: bindGroupLayout,
+    entries: bindEntries,
+  });
+
+  return {
+    key, pipeline, bindGroup, globals, globalsStaging, drawHeap, drawStaging,
+    packed, trafos: myTrafos, colors: myColors, dirty, subs,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface HeapDrawSpec {
+  readonly geo: HeapGeometry;
+  readonly modelTrafo: aval<Trafo3d> | Trafo3d;
+  readonly color: aval<V4f> | V4f;
+  /** Group key — selects which pipeline-state group this draw joins. */
+  readonly groupKey: string;
+}
+
+export interface HeapSceneStats {
+  readonly groups: number;
+  readonly totalDraws: number;
+  readonly globalsBytes: number;
+  drawBytes: number;
+  readonly geometryBytes: number;
+}
+
+export interface HeapScene {
+  /** Render one frame against the given globals. */
+  frame(viewProj: Trafo3d, lightLocation: V3d): void;
+  readonly stats: HeapSceneStats;
+  dispose(): void;
+}
+
+/**
+ * Per-group texture set. Bindless isn't standard WebGPU, so a group
+ * with sampled textures gets a distinct bind-group layout and is
+ * keyed separately from groups with no textures or different sets.
+ */
+export interface HeapTextureSet {
+  readonly texture: GPUTexture;
+  readonly textureView?: GPUTextureView;
+  readonly sampler: GPUSampler;
+}
+
+export interface BuildHeapSceneOptions {
+  /** WGSL fragment-stage source per group key — must declare `fs(in: VsOut) -> @location(0) vec4<f32>`. */
+  readonly fragmentShaders: ReadonlyMap<string, string>;
+  /**
+   * Per-group texture set. When present, the group's bind-group
+   * layout adds a `texture_2d<f32>` at binding 4 and a sampler at
+   * binding 5. The user's FS WGSL must declare them.
+   */
+  readonly texturesByGroupKey?: ReadonlyMap<string, HeapTextureSet>;
+}
+
+/**
+ * Build a multi-group heap-backed scene renderer. Buckets `draws` by
+ * `groupKey`, builds one pipeline + bind group + heap per bucket,
+ * subscribes per-RO avals so dirty marks propagate to per-slot
+ * `writeBuffer`s on the next `frame()`.
+ */
+export function buildHeapScene(
+  device: GPUDevice,
+  attach: CanvasAttachment,
+  draws: readonly HeapDrawSpec[],
+  opts: BuildHeapSceneOptions,
+): HeapScene {
+  const modelTrafos: aval<Trafo3d>[] = draws.map(d => asAval(d.modelTrafo));
+  const colors:      aval<V4f>[]    = draws.map(d => asAval(d.color));
+
+  // Bucket by group key.
+  const buckets = new Map<string, { spec: HeapDrawSpec; sourceIndex: number }[]>();
+  for (let i = 0; i < draws.length; i++) {
+    const d = draws[i]!;
+    let bucket = buckets.get(d.groupKey);
+    if (bucket === undefined) {
+      bucket = [];
+      buckets.set(d.groupKey, bucket);
+    }
+    bucket.push({ spec: d, sourceIndex: i });
+  }
+  const groups: Group[] = [];
+  for (const [key, members] of buckets) {
+    const fs = opts.fragmentShaders.get(key);
+    if (fs === undefined) {
+      throw new Error(`buildHeapScene: no fragment shader supplied for groupKey '${key}'`);
+    }
+    const textureSet = opts.texturesByGroupKey?.get(key);
+    groups.push(buildGroup(device, attach, key, fs, textureSet, members, modelTrafos, colors));
+  }
+
+  const stats: HeapSceneStats = {
+    groups: groups.length,
+    totalDraws: draws.length,
+    globalsBytes: GLOBALS_BYTES * groups.length,
+    drawBytes: 0,
+    geometryBytes: groups.reduce((acc, g) => acc + g.packed.bytes, 0),
+  };
+
+  function frame(viewProj: Trafo3d, lightLocation: V3d): void {
+    const fb = (attach.framebuffer as aval<import("../core/index.js").IFramebuffer>).force(/* allow-force */);
+    const colorAttachmentName = attach.signature.colorNames[0]!;
+    const colorView = fb.colors.tryFind(colorAttachmentName)!;
+    const depthFormat = attach.signature.depthStencil?.format;
+    const depthView = fb.depthStencil;
+
+    let totalDirtyBytes = 0;
+
+    const enc = device.createCommandEncoder({ label: "heapScene: encoder" });
+    let firstPass = true;
+    for (const g of groups) {
+      packGlobals(viewProj, lightLocation, g.globalsStaging);
+      device.queue.writeBuffer(g.globals, 0, g.globalsStaging.buffer, g.globalsStaging.byteOffset, GLOBALS_BYTES);
+
+      if (g.dirty.size > 0) {
+        for (const i of g.dirty) {
+          packDrawHeader(
+            g.trafos[i]!.force(/* allow-force */),
+            g.colors[i]!.force(/* allow-force */),
+            g.packed.entries[i]!.vertexBase, g.drawStaging, i,
+          );
+          const byteOff = i * DRAW_HEADER_BYTES;
+          device.queue.writeBuffer(
+            g.drawHeap, byteOff,
+            g.drawStaging.buffer, g.drawStaging.byteOffset + byteOff,
+            DRAW_HEADER_BYTES,
+          );
+          totalDirtyBytes += DRAW_HEADER_BYTES;
+        }
+        g.dirty.clear();
+      }
+
+      const pass = enc.beginRenderPass({
+        colorAttachments: [{
+          view: colorView,
+          clearValue: { r: 0.07, g: 0.07, b: 0.08, a: 1.0 },
+          loadOp: firstPass ? "clear" : "load",
+          storeOp: "store",
+        }],
+        ...(depthView !== undefined && depthFormat !== undefined ? {
+          depthStencilAttachment: {
+            view: depthView,
+            depthClearValue: 1.0,
+            depthLoadOp: firstPass ? "clear" : "load",
+            depthStoreOp: "store",
+          } satisfies GPURenderPassDepthStencilAttachment,
+        } : {}),
+      });
+      pass.setPipeline(g.pipeline);
+      pass.setBindGroup(0, g.bindGroup);
+      pass.setIndexBuffer(g.packed.indexBuf, "uint32");
+      for (let i = 0; i < g.packed.entries.length; i++) {
+        const e = g.packed.entries[i]!;
+        pass.drawIndexed(e.indexCount, 1, e.firstIndex, 0, i);
+      }
+      pass.end();
+      firstPass = false;
+    }
+
+    stats.drawBytes = totalDirtyBytes;
+    device.queue.submit([enc.finish()]);
+  }
+
+  function dispose(): void {
+    for (const g of groups) {
+      for (const s of g.subs) s.dispose();
+      g.globals.destroy();
+      g.drawHeap.destroy();
+      g.packed.positionsBuf.destroy();
+      g.packed.normalsBuf.destroy();
+      g.packed.indexBuf.destroy();
+    }
+  }
+
+  return { frame, stats, dispose };
+}

package/src/runtime/index.ts

@@ -22,3 +22,13 @@ export {
   ScenePass,
   type WalkerStats,
 } from "./scenePass.js";
+
+export {
+  buildHeapScene,
+  type HeapScene,
+  type HeapSceneStats,
+  type HeapDrawSpec,
+  type HeapGeometry,
+  type HeapTextureSet,
+  type BuildHeapSceneOptions,
+} from "./heapScene.js";