@aardworx/wombat.rendering 0.8.1 → 0.9.1

package/dist/runtime/textureAtlas/atlasMipGutterKernel.js

@@ -0,0 +1,247 @@
+// Compute kernel that builds an atlas sub-rect's mip pyramid AND fills
+// both gutter rings entirely on GPU, using only core WebGPU 1.0
+// features (no `readonly-and-readwrite-storage-textures`).
+//
+// Architecture
+// ============
+// The whole operation runs inside a per-acquire **scratch buffer**
+// laid out exactly like the destination region of the atlas page
+// (bounding rect of the Iliffe pyramid + gutter, in atlas-pixel
+// coordinates relative to the sub-rect origin). Each pixel is one
+// packed `u32` (rgba8). Rows are padded to 256-byte alignment so the
+// final `copyBufferToTexture` is straight-through.
+//
+// Per acquire:
+//   1. CPU writes the raw source pixels into the scratch buffer at
+//      the mip-0 interior offset (via `mappedAtCreation`). One JS
+//      loop, no upload validation pitfalls.
+//   2. For each mip k > 0: dispatch the `interior` kernel, which
+//      reads 2×2 from mip-(k-1) in the buffer and writes the average
+//      to mip-k interior, all in-buffer. Each mip lives in its own
+//      compute pass — the pass boundary acts as a barrier so
+//      mip-(k-1) is fully written before mip-k reads from it.
+//   3. For each mip k: dispatch the `gutter` kernel, which copies
+//      the appropriate clamp / wrap interior cell into each gutter
+//      cell. Also one compute pass per mip.
+//   4. `copyBufferToTexture` writes the full scratch buffer to the
+//      atlas page at the sub-rect origin.
+//
+// The kernel reads and writes ONE storage buffer through a
+// `read_write` binding. WebGPU validates a single binding (even with
+// read_write access) as one usage entry per resource — no hazard.
+//
+// No device features required. No same-texture binding pitfalls. The
+// scratch buffer is per-acquire and freed after submission completes.
+const WGSL = /* wgsl */ `
+struct Params {
+  buf_stride_u32:    u32,
+  _pad0:             u32,
+  src_origin_in_buf: vec2<u32>,
+  src_size:          vec2<u32>,
+  dst_origin_in_buf: vec2<u32>,
+  dst_size:          vec2<u32>,
+}
+
+@group(0) @binding(0) var<storage, read_write> buf: array<u32>;
+@group(0) @binding(1) var<uniform> P: Params;
+
+fn loadRgba(x: u32, y: u32) -> vec4<f32> {
+  let idx = y * P.buf_stride_u32 + x;
+  return unpack4x8unorm(buf[idx]);
+}
+
+fn storeRgba(x: u32, y: u32, v: vec4<f32>) {
+  let idx = y * P.buf_stride_u32 + x;
+  buf[idx] = pack4x8unorm(v);
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn interior(@builtin(global_invocation_id) gid: vec3<u32>) {
+  if (gid.x >= P.dst_size.x || gid.y >= P.dst_size.y) { return; }
+  let sx0 = P.src_origin_in_buf.x + gid.x * 2u;
+  let sy0 = P.src_origin_in_buf.y + gid.y * 2u;
+  let sxMax = P.src_origin_in_buf.x + P.src_size.x - 1u;
+  let syMax = P.src_origin_in_buf.y + P.src_size.y - 1u;
+  let sx1 = min(sx0 + 1u, sxMax);
+  let sy1 = min(sy0 + 1u, syMax);
+  let a = loadRgba(sx0, sy0);
+  let b = loadRgba(sx1, sy0);
+  let c = loadRgba(sx0, sy1);
+  let d = loadRgba(sx1, sy1);
+  let avg = (a + b + c + d) * 0.25;
+  storeRgba(P.dst_origin_in_buf.x + gid.x, P.dst_origin_in_buf.y + gid.y, avg);
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn gutter(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let totW = P.dst_size.x + 4u;
+  let totH = P.dst_size.y + 4u;
+  if (gid.x >= totW || gid.y >= totH) { return; }
+  let dx = i32(gid.x) - 2;
+  let dy = i32(gid.y) - 2;
+  let dw = i32(P.dst_size.x);
+  let dh = i32(P.dst_size.y);
+  if (dx >= 0 && dx < dw && dy >= 0 && dy < dh) { return; }
+  var sx: i32;
+  var sy: i32;
+       if (dx == -2)     { sx = dw - 1; }
+  else if (dx == -1)     { sx = 0; }
+  else if (dx == dw)     { sx = dw - 1; }
+  else if (dx == dw + 1) { sx = 0; }
+  else                   { sx = dx; }
+       if (dy == -2)     { sy = dh - 1; }
+  else if (dy == -1)     { sy = 0; }
+  else if (dy == dh)     { sy = dh - 1; }
+  else if (dy == dh + 1) { sy = 0; }
+  else                   { sy = dy; }
+  let v = loadRgba(u32(i32(P.dst_origin_in_buf.x) + sx),
+                   u32(i32(P.dst_origin_in_buf.y) + sy));
+  storeRgba(u32(i32(P.dst_origin_in_buf.x) + dx),
+            u32(i32(P.dst_origin_in_buf.y) + dy),
+            v);
+}
+`;
+const caches = new WeakMap();
+function getKernel(device) {
+    const cached = caches.get(device);
+    if (cached !== undefined)
+        return cached;
+    const module = device.createShaderModule({ code: WGSL, label: "atlas/mipGutterKernel" });
+    const bindGroupLayout = device.createBindGroupLayout({
+        label: "atlas/mipGutterKernel/bgl",
+        entries: [
+            { binding: 0, visibility: 0x4 /* COMPUTE */, buffer: { type: "storage" } },
+            { binding: 1, visibility: 0x4 /* COMPUTE */, buffer: { type: "uniform" } },
+        ],
+    });
+    const layout = device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout] });
+    const interiorPipeline = device.createComputePipeline({
+        layout, compute: { module, entryPoint: "interior" },
+        label: "atlas/mipGutterKernel/interior",
+    });
+    const gutterPipeline = device.createComputePipeline({
+        layout, compute: { module, entryPoint: "gutter" },
+        label: "atlas/mipGutterKernel/gutter",
+    });
+    const entry = { bindGroupLayout, interiorPipeline, gutterPipeline };
+    caches.set(device, entry);
+    return entry;
+}
+/**
+ * Build the mip pyramid + gutters on GPU and upload the result to a
+ * sub-rect of `page`. `srcPixels` is the raw RGBA8 source for mip 0
+ * (`srcW × srcH` pixels). The kernel:
+ *   - Allocates a per-acquire scratch buffer.
+ *   - Initialises the buffer at creation with mip-0 source pixels at
+ *     the mip-0 interior offset.
+ *   - Dispatches per-mip interior + gutter compute passes.
+ *   - copyBufferToTexture into the page at (subRectX, subRectY).
+ *
+ * Caller must ensure the page has COPY_DST usage (atlas pages
+ * always do).
+ *
+ * Buffer is destroyed once submitted work completes (fire-and-forget
+ * via `onSubmittedWorkDone`).
+ */
+export function buildMipsAndGutterOnGpu(device, page, subRectX, subRectY, boundsW, boundsH, srcPixels, srcW, srcH, mips) {
+    if (mips.length === 0)
+        return;
+    const { bindGroupLayout, interiorPipeline, gutterPipeline } = getKernel(device);
+    // Buffer layout: rows padded to 256 bytes for the final
+    // copyBufferToTexture. Stride in u32: 256 / 4 = 64 minimum, or
+    // ceil(boundsW * 4 / 256) * 256 / 4.
+    const rowBytes = Math.max(256, Math.ceil(boundsW * 4 / 256) * 256);
+    const bufStrideU32 = rowBytes / 4;
+    const bufSize = rowBytes * boundsH;
+    const scratch = device.createBuffer({
+        label: `atlas/mipGutter/scratch(${boundsW}x${boundsH})`,
+        size: bufSize,
+        usage: 0x80 /* STORAGE */ | 0x04 /* COPY_SRC */ | 0x08 /* COPY_DST */,
+        mappedAtCreation: true,
+    });
+    // CPU init: write mip-0 source pixels at the mip-0 interior offset
+    // inside the buffer. mips[0].origin is the interior offset.
+    const mip0 = mips[0];
+    {
+        const mapped = new Uint32Array(scratch.getMappedRange());
+        for (let y = 0; y < srcH; y++) {
+            for (let x = 0; x < srcW; x++) {
+                const si = (y * srcW + x) * 4;
+                const r = srcPixels[si];
+                const g = srcPixels[si + 1];
+                const b = srcPixels[si + 2];
+                const a = srcPixels[si + 3];
+                // little-endian rgba8: byte0=r, byte1=g, byte2=b, byte3=a.
+                const packed = (a << 24) | (b << 16) | (g << 8) | r;
+                mapped[(mip0.origin.y + y) * bufStrideU32 + (mip0.origin.x + x)] = packed >>> 0;
+            }
+        }
+    }
+    scratch.unmap();
+    const enc = device.createCommandEncoder({ label: "atlas/mipGutterKernel" });
+    const ubos = [];
+    const makeUbo = (srcO, srcS, dstO, dstS) => {
+        const buf = device.createBuffer({
+            size: 48, // 12 u32, padded
+            usage: 0x40 /* UNIFORM */ | 0x08 /* COPY_DST */,
+            label: "atlas/mipGutter/params",
+        });
+        const u = new Uint32Array(12);
+        u[0] = bufStrideU32;
+        u[1] = 0;
+        u[2] = srcO.x;
+        u[3] = srcO.y;
+        u[4] = srcS.w;
+        u[5] = srcS.h;
+        u[6] = dstO.x;
+        u[7] = dstO.y;
+        u[8] = dstS.w;
+        u[9] = dstS.h;
+        device.queue.writeBuffer(buf, 0, u);
+        ubos.push(buf);
+        return buf;
+    };
+    const makeBg = (ubo) => device.createBindGroup({
+        layout: bindGroupLayout,
+        entries: [
+            { binding: 0, resource: { buffer: scratch } },
+            { binding: 1, resource: { buffer: ubo } },
+        ],
+    });
+    // Interior passes: one compute pass per mip > 0 (pass boundary
+    // gives us the barrier ensuring mip-(k-1) is fully written before
+    // mip-k reads it).
+    for (let k = 1; k < mips.length; k++) {
+        const src = mips[k - 1];
+        const dst = mips[k];
+        const ubo = makeUbo(src.origin, src.size, dst.origin, dst.size);
+        const pass = enc.beginComputePass({ label: `atlas/mipGutter/interior/${k}` });
+        pass.setPipeline(interiorPipeline);
+        pass.setBindGroup(0, makeBg(ubo));
+        pass.dispatchWorkgroups(Math.ceil(dst.size.w / 8), Math.ceil(dst.size.h / 8), 1);
+        pass.end();
+    }
+    // Gutter passes: one per mip (each pass reads mip-k interior,
+    // which was either CPU-uploaded for k=0 or written by the interior
+    // pass for k>0).
+    for (let k = 0; k < mips.length; k++) {
+        const dst = mips[k];
+        const ubo = makeUbo(dst.origin, dst.size, dst.origin, dst.size);
+        const pass = enc.beginComputePass({ label: `atlas/mipGutter/gutter/${k}` });
+        pass.setPipeline(gutterPipeline);
+        pass.setBindGroup(0, makeBg(ubo));
+        pass.dispatchWorkgroups(Math.ceil((dst.size.w + 4) / 8), Math.ceil((dst.size.h + 4) / 8), 1);
+        pass.end();
+    }
+    // Final upload: buffer → page.
+    enc.copyBufferToTexture({ buffer: scratch, bytesPerRow: rowBytes, rowsPerImage: boundsH }, { texture: page, origin: { x: subRectX, y: subRectY, z: 0 } }, { width: boundsW, height: boundsH, depthOrArrayLayers: 1 });
+    device.queue.submit([enc.finish()]);
+    // Lifetime: destroy scratch + per-pass UBOs once submitted work is
+    // done. The submit holds a ref until completion.
+    void device.queue.onSubmittedWorkDone().then(() => {
+        scratch.destroy();
+        for (const b of ubos)
+            b.destroy();
+    });
+}
+//# sourceMappingURL=atlasMipGutterKernel.js.map

package/dist/runtime/textureAtlas/atlasMipGutterKernel.js.map

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

package/dist/runtime/textureAtlas/atlasPool.d.ts

@@ -0,0 +1,240 @@
+import { V2f } from "@aardworx/wombat.base";
+import type { aval } from "@aardworx/wombat.adaptive";
+import type { ITexture, HostTextureSource } from "../../core/texture.js";
+import { TexturePacking } from "./packer.js";
+export declare const ATLAS_PAGE_SIZE = 4096;
+/** Tier S/M source-side dimension cap. */
+export declare const ATLAS_MAX_DIM = 1024;
+/**
+ * Maximum number of independent pages allowed per format. The shader's
+ * `switch pageRef` runs an N-way ladder; the BGL declares N consecutive
+ * texture slots per format. Allocations beyond this throw.
+ */
+export declare const ATLAS_MAX_PAGES_PER_FORMAT = 8;
+export type AtlasPageFormat = "rgba8unorm" | "rgba8unorm-srgb";
+export declare const ATLAS_PAGE_FORMATS: readonly AtlasPageFormat[];
+/** Format index used in the drawHeader: 0 = linear, 1 = srgb. */
+export declare const atlasFormatIndex: (f: AtlasPageFormat) => number;
+export interface AtlasPage {
+    readonly format: AtlasPageFormat;
+    /**
+     * The page's own independent `GPUTexture` (dimension: "2d", single
+     * 4096² image). Stable for the page's lifetime — never reallocated.
+     */
+    readonly texture: GPUTexture;
+    /** Immutable packer state — `tryAdd`/`remove` produce new instances. */
+    packing: TexturePacking<number>;
+    /**
+     * Page slot index in the format's binding sequence (0..N-1). Same
+     * value flows into the drawHeader `pageRef` field; the shader's
+     * `switch pageRef` selects the matching `atlasLinear<i>` /
+     * `atlasSrgb<i>` declaration.
+     */
+    readonly pageId: number;
+}
+export interface AtlasAcquisition {
+    /** Page slot index within the format's binding sequence (0..N-1). */
+    readonly pageId: number;
+    /** Top-left of mip 0's interior in the atlas, in atlas pixels. */
+    readonly origin: V2f;
+    /** Size of mip 0's interior in the atlas, in atlas pixels. */
+    readonly size: V2f;
+    /** Number of mip levels stored for this acquisition (1 = no pyramid). */
+    readonly numMips: number;
+    /** Stable refcount handle: pass back to `release`. */
+    readonly ref: number;
+    /** The page's GPUTexture (so the caller can pin it in the bind group). */
+    readonly page: AtlasPage;
+}
+/** Source descriptor accepted by `acquire` (small enough not to need a full ITexture). */
+export interface AtlasSource {
+    readonly width: number;
+    readonly height: number;
+    /**
+     * The host source for upload. The pool calls
+     * `device.queue.copyExternalImageToTexture` (external) or
+     * `writeTexture` (raw) into the page region the first time the
+     * sub-rect is allocated. For mipped uploads the pool downscales
+     * via canvas-2d and uploads each level into the pyramid sub-region.
+     */
+    readonly host?: HostTextureSource;
+}
+export interface AtlasAcquireOptions {
+    readonly source?: AtlasSource;
+    /** When true, reserve a 1.5W×H rect and store an embedded mip pyramid. */
+    readonly wantsMips?: boolean;
+    /**
+     * Number of mip levels to store. Defaults to
+     * `floor(log2(max(w,h))) + 1` (full chain to 1×1).
+     */
+    readonly numMips?: number;
+}
+/**
+ * Default mip count for a `w×h` source: full chain down to 1×1.
+ */
+export declare const defaultMipCount: (w: number, h: number) => number;
+/**
+ * Mip-k pixel size given mip-0 size `(w,h)`. Halves each level and
+ * floors at 1×1.
+ */
+export declare const mipPixelSize: (w: number, h: number, k: number) => {
+    w: number;
+    h: number;
+};
+/**
+ * Mip-k interior offset from mip-0 interior, both inside the embedded
+ * Iliffe pyramid. Mip 0 is at (0,0). Mips 1..N stack vertically in
+ * the column at x = W + 4 (mip-0 width + 2 px right gutter of mip-0
+ * + 2 px left gutter of the mip column). Each mip k>=1 sits below
+ * mip k-1 with 4 px of vertical gutter between them (2 px bottom of
+ * mip k-1 + 2 px top of mip k):
+ *   y_k = sum_{j=1..k-1} (max(1, H >> j) + 4).
+ * Caller writes at `(uploadOrigin + mipOffsetInPyramid(w, h, k))`
+ * where uploadOrigin is mip-0's interior pixel position.
+ */
+export declare const mipOffsetInPyramid: (w: number, h: number, k: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * Aval-identity keyed pool over the per-format page sets. Multiple
+ * acquisitions of the same `aval<ITexture>` share one sub-rect; the
+ * refcount drives release.
+ */
+export declare class AtlasPool {
+    private readonly device;
+    private readonly pagesByFormat;
+    private readonly pageAddedListeners;
+    private readonly entriesByAval;
+    private readonly entriesByRef;
+    /**
+     * §5b value-equality dedup map. Constant avals (`isConstant ===
+     * true`) wrapping the same inner GPUTexture (kind:"gpu") or
+     * HostTextureSource (kind:"host") collapse to one sub-rect.
+     * Reactive avals fall through to identity-only since their
+     * content can change.
+     */
+    private readonly entriesByValueKey;
+    private nextRef;
+    private innerKeyOf;
+    constructor(device: GPUDevice);
+    /** All currently allocated pages for a given format. */
+    pagesFor(format: AtlasPageFormat): readonly AtlasPage[];
+    /**
+     * Subscribe to page-allocation events. Fires after a fresh
+     * `AtlasPage` is appended to the format's page list (its `pageId`
+     * is the slot the bind group should now wire up).
+     */
+    onPageAdded(format: AtlasPageFormat, cb: (pageId: number) => void): {
+        dispose(): void;
+    };
+    /** True for pages we can drive via the compute mip+gutter kernel.
+     *  The kernel is buffer-based: it allocates a scratch storage
+     *  buffer matching the sub-rect's bounding box, runs all mip
+     *  downscale + gutter fill in compute passes over the buffer, then
+     *  one `copyBufferToTexture` uploads the whole region to the page.
+     *  No texture storage bindings are needed and no device features
+     *  are required — works in core WebGPU 1.0. The only constraint is
+     *  that JS-side pixel extraction succeeds, which falls back to the
+     *  CPU path on headless platforms without canvas.
+     *
+     *  Disabled in node mock-GPU mode (which lacks queue.onSubmittedWorkDone). */
+    private canUseGpuKernel;
+    private allocatePage;
+    /**
+     * Tier-S eligibility: dimension threshold + supported format. If
+     * this returns null, the caller should route the texture down the
+     * Tier L (standalone) path.
+     */
+    static eligibleFormat(format: GPUTextureFormat): AtlasPageFormat | null;
+    static eligibleSize(width: number, height: number): boolean;
+    /**
+     * Acquire (or share) a sub-rect. The returned `AtlasAcquisition`
+     * gives the page slot index plus the mip-0 `origin`/`size` (in
+     * normalized atlas coords) and `numMips`. If the texture is already
+     * known (same aval), refcount bumps and we return the existing
+     * placement.
+     */
+    acquire(format: AtlasPageFormat, sourceAval: aval<ITexture>, width: number, height: number, opts?: AtlasAcquireOptions): AtlasAcquisition;
+    /**
+     * Look up the existing acquisition for a source aval, or `undefined`
+     * if the aval is not currently held in the pool. Mirrors
+     * `UniformPool.entry` — used by the heap path's reactivity loop to
+     * detect "this aval has live refs and just marked".
+     */
+    entry(sourceAval: aval<ITexture>): AtlasAcquisition | undefined;
+    /**
+     * Re-pack an aval's atlas placement against a new ITexture value.
+     * Mirrors `UniformPool.repack(av, newValue)` — used when an atlas-
+     * routed `aval<ITexture>` source swaps. Frees the old sub-rect (and
+     * the page slot in the packer) and acquires a fresh one for the new
+     * texture; the returned `AtlasAcquisition` carries the (potentially
+     * different) `pageId`/`origin`/`size`/`numMips`/`ref`. Refcount is
+     * preserved across the swap so multi-RO sharing keeps working.
+     *
+     * Throws if the new texture isn't Tier-S eligible (different format
+     * outside rgba8unorm/srgb, or larger than the cap). Callers should
+     * rely on the heap eligibility classifier, but this is a safety net.
+     */
+    repack(sourceAval: aval<ITexture>, newTexture: ITexture, opts?: AtlasAcquireOptions): AtlasAcquisition;
+    /** Decrement the refcount; on zero, free the sub-rect. */
+    release(ref: number): void;
+    /** Destroy every page texture. The pool becomes unusable. */
+    dispose(): void;
+    private finalize;
+    private upload;
+    /**
+     * Build a (w+4)×(h+4) extended pixel buffer from `src` (w×h, RGBA8)
+     * with the 2-px gutter pre-filled:
+     *   - Inner ring (1 px) = clamp-replicate (edge texel).
+     *   - Outer ring (1 px) = wrap (opposite-edge texel).
+     * The shader needs both: clamp-replicate absorbs FP-edge bleed for
+     * any wrap mode; the outer wrap ring is sampled by the repeat
+     * seam-shift ±1 path. By pre-baking these CPU-side we get a single
+     * writeTexture call per slot — much faster than per-cell GPU
+     * copies, and dodges Dawn's overly-strict same-texture copy
+     * validation.
+     *
+     * Layout matches the shader expectations and `placeWithGutter` in
+     * the conformance test. Corner cells are populated by independent
+     * per-axis interpretation (e.g. outer-X × outer-Y = diagonal wrap;
+     * inner-X × outer-Y = clamp-X × wrap-Y).
+     */
+    private static buildExtendedWithGutter;
+    /**
+     * Extract raw RGBA8 pixels from `host` at logical size (w, h).
+     * Falls back to a canvas draw + getImageData for external sources;
+     * raw sources are copied straight. Returns null when the runtime
+     * can't synthesise pixels (headless without canvas, etc.).
+     */
+    private extractPixels;
+    /**
+     * Upload a mip level INCLUDING its 2-px gutter ring. Writes a
+     * single (w+4)×(h+4) block to (x-2, y-2) — caller passes the
+     * interior position (x, y), this routine offsets by -2/-2 to
+     * cover the gutter. Returns false if pixel extraction failed (very
+     * rare; only on platforms without canvas support).
+     */
+    private uploadLevelWithGutter;
+    /** Unused stub kept for compatibility — see uploadLevelWithGutter. */
+    private fillClampGutter;
+    private uploadLevel;
+    /**
+     * Upload `src` (RGBA8, w×h) to `texture` at (x, y) via `writeTexture`.
+     * `writeTexture` requires `bytesPerRow` to be a multiple of 256 when
+     * the source has more than one row, so non-256-aligned widths need
+     * a padded buffer.
+     */
+    private writeRgba8Padded;
+    /**
+     * Produce a `CanvasImageSource` we can feed to `drawImage` for
+     * downscaling. Returns null when the runtime can't synthesise one
+     * (no DOM / OffscreenCanvas / ImageBitmap support).
+     */
+    private toDrawable;
+    private imageDataToCanvas;
+    private makeMipCanvas;
+    private makeCanvas;
+    private makeResult;
+}
+//# sourceMappingURL=atlasPool.d.ts.map

package/dist/runtime/textureAtlas/atlasPool.d.ts.map

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