@aardworx/wombat.rendering 0.1.0

package/src/resources/adaptiveTexture.ts

@@ -0,0 +1,269 @@
+// prepareAdaptiveTexture — lift `aval<ITexture>` to
+// `AdaptiveResource<GPUTexture>`.
+//
+// Behaviour matches `prepareAdaptiveBuffer`: on `compute`, if the
+// source is `gpu` return the user's handle; if `host`, ensure we
+// own a GPUTexture of the right size/format and upload via the
+// queue (writeTexture for raw, copyExternalImageToTexture for
+// external sources).
+//
+// Reuse: a host source with the same dimensions + format reuses
+// the existing texture; mismatch triggers a fresh allocation.
+//
+// Mip-map generation is not implemented in this first cut —
+// `generateMips: true` on an external source allocates the mip
+// levels but only mip 0 is uploaded. (Mip generation requires a
+// compute pass; that lands in a follow-up.)
+
+import {
+  AdaptiveResource,
+  tryAcquire,
+  tryRelease,
+  type ITexture,
+  type ExternalTextureSource,
+  type RawTextureSource,
+} from "../core/index.js";
+import {
+  type AdaptiveToken,
+  type aval,
+} from "@aardworx/wombat.adaptive";
+import { TextureUsage } from "./webgpuFlags.js";
+
+export interface PrepareAdaptiveTextureOptions {
+  /** Extra usage flags. `COPY_DST` and `TEXTURE_BINDING` are added automatically. */
+  readonly usage?: GPUTextureUsageFlags;
+  /** Optional debug label. */
+  readonly label?: string;
+}
+
+interface OwnedDesc {
+  width: number;
+  height: number;
+  depthOrArrayLayers: number;
+  format: GPUTextureFormat;
+  mipLevelCount: number;
+}
+
+function descsEqual(a: OwnedDesc, b: OwnedDesc): boolean {
+  return (
+    a.width === b.width
+    && a.height === b.height
+    && a.depthOrArrayLayers === b.depthOrArrayLayers
+    && a.format === b.format
+    && a.mipLevelCount === b.mipLevelCount
+  );
+}
+
+function descFor(src: RawTextureSource | ExternalTextureSource): OwnedDesc {
+  if (src.kind === "raw") {
+    return {
+      width: src.width,
+      height: src.height,
+      depthOrArrayLayers: src.depthOrArrayLayers ?? 1,
+      format: src.format,
+      mipLevelCount: src.mipLevelCount ?? 1,
+    };
+  }
+  // external
+  const s = src.source;
+  let width = 0;
+  let height = 0;
+  if (s instanceof ImageData) {
+    width = s.width; height = s.height;
+  } else if ("naturalWidth" in s && typeof s.naturalWidth === "number") {
+    // HTMLImageElement
+    width = s.naturalWidth || s.width;
+    height = s.naturalHeight || s.height;
+  } else if ("videoWidth" in s && typeof s.videoWidth === "number") {
+    // HTMLVideoElement
+    width = s.videoWidth; height = s.videoHeight;
+  } else {
+    // ImageBitmap, HTMLCanvasElement, OffscreenCanvas — all have width/height
+    width = (s as { width: number }).width;
+    height = (s as { height: number }).height;
+  }
+  const generateMips = src.generateMips === true;
+  return {
+    width, height, depthOrArrayLayers: 1,
+    format: src.format ?? "rgba8unorm",
+    mipLevelCount: generateMips ? mipCount(width, height) : 1,
+  };
+}
+
+function mipCount(w: number, h: number): number {
+  return Math.floor(Math.log2(Math.max(w, h))) + 1;
+}
+
+class AdaptiveTexture extends AdaptiveResource<GPUTexture> {
+  private _owned: GPUTexture | undefined = undefined;
+  private _ownedDesc: OwnedDesc | undefined = undefined;
+
+  constructor(
+    private readonly device: GPUDevice,
+    private readonly source: aval<ITexture>,
+    private readonly opts: PrepareAdaptiveTextureOptions,
+  ) {
+    super();
+  }
+
+  protected create(): void { tryAcquire(this.source); }
+
+  protected destroy(): void {
+    if (this._owned !== undefined) {
+      this._owned.destroy();
+      this._owned = undefined;
+      this._ownedDesc = undefined;
+    }
+    tryRelease(this.source);
+  }
+
+  override compute(token: AdaptiveToken): GPUTexture {
+    const src = this.source.getValue(token);
+    if (src.kind === "gpu") {
+      if (this._owned !== undefined) {
+        this._owned.destroy();
+        this._owned = undefined;
+        this._ownedDesc = undefined;
+      }
+      return src.texture;
+    }
+    const desc = descFor(src.source);
+    const usage =
+      (this.opts.usage ?? 0)
+      | TextureUsage.COPY_DST
+      | TextureUsage.TEXTURE_BINDING
+      | (src.source.kind === "external" ? TextureUsage.RENDER_ATTACHMENT : 0);
+    if (this._owned === undefined || this._ownedDesc === undefined || !descsEqual(this._ownedDesc, desc)) {
+      if (this._owned !== undefined) this._owned.destroy();
+      const tdesc: GPUTextureDescriptor = {
+        size: { width: desc.width, height: desc.height, depthOrArrayLayers: desc.depthOrArrayLayers },
+        format: desc.format,
+        mipLevelCount: desc.mipLevelCount,
+        usage,
+        ...(this.opts.label !== undefined ? { label: this.opts.label } : {}),
+      };
+      this._owned = this.device.createTexture(tdesc);
+      this._ownedDesc = desc;
+    }
+    if (src.source.kind === "raw") {
+      uploadRaw(this.device, this._owned, src.source);
+    } else {
+      uploadExternal(this.device, this._owned, src.source);
+    }
+    return this._owned;
+  }
+}
+
+function uploadRaw(device: GPUDevice, tex: GPUTexture, src: RawTextureSource): void {
+  const bytes = src.data instanceof ArrayBuffer ? new Uint8Array(src.data) : new Uint8Array(src.data.buffer, src.data.byteOffset, src.data.byteLength);
+  const block = blockInfoFor(src.format);
+  const blocksPerRow = Math.ceil(src.width / block.width);
+  const rowsOfBlocks = Math.ceil(src.height / block.height);
+  device.queue.writeTexture(
+    { texture: tex },
+    bytes as unknown as GPUAllowSharedBufferSource,
+    { bytesPerRow: blocksPerRow * block.bytesPerBlock, rowsPerImage: rowsOfBlocks },
+    { width: src.width, height: src.height, depthOrArrayLayers: src.depthOrArrayLayers ?? 1 },
+  );
+}
+
+function uploadExternal(device: GPUDevice, tex: GPUTexture, src: ExternalTextureSource): void {
+  device.queue.copyExternalImageToTexture(
+    { source: src.source as GPUImageCopyExternalImageSource },
+    { texture: tex },
+    { width: (src.source as { width: number }).width, height: (src.source as { height: number }).height, depthOrArrayLayers: 1 },
+  );
+}
+
+interface BlockInfo {
+  readonly width: number;        // pixels per block in x
+  readonly height: number;       // pixels per block in y
+  readonly bytesPerBlock: number;
+}
+
+/**
+ * Block dimensions + size for a WebGPU texture format. Linear
+ * (uncompressed) formats report 1×1 blocks. Block-compressed
+ * formats (BC*, ETC*, ASTC*, EAC) use their native block size so
+ * `writeTexture`'s bytesPerRow / rowsPerImage land on the right
+ * block grid.
+ */
+function blockInfoFor(format: GPUTextureFormat): BlockInfo {
+  switch (format) {
+    // 8-bit
+    case "r8unorm": case "r8snorm": case "r8uint": case "r8sint":
+      return { width: 1, height: 1, bytesPerBlock: 1 };
+    // 16-bit
+    case "rg8unorm": case "rg8snorm": case "rg8uint": case "rg8sint":
+    case "r16uint": case "r16sint": case "r16float":
+      return { width: 1, height: 1, bytesPerBlock: 2 };
+    // 32-bit
+    case "rgba8unorm": case "rgba8unorm-srgb": case "rgba8snorm":
+    case "rgba8uint": case "rgba8sint":
+    case "bgra8unorm": case "bgra8unorm-srgb":
+    case "rgb10a2unorm": case "rgb10a2uint":
+    case "rg11b10ufloat": case "rgb9e5ufloat":
+    case "rg16uint": case "rg16sint": case "rg16float":
+    case "r32uint": case "r32sint": case "r32float":
+      return { width: 1, height: 1, bytesPerBlock: 4 };
+    // 64-bit
+    case "rgba16uint": case "rgba16sint": case "rgba16float":
+    case "rg32uint": case "rg32sint": case "rg32float":
+      return { width: 1, height: 1, bytesPerBlock: 8 };
+    // 128-bit
+    case "rgba32uint": case "rgba32sint": case "rgba32float":
+      return { width: 1, height: 1, bytesPerBlock: 16 };
+
+    // ---- Block-compressed formats ----
+    // BC1/2/3/4/5 (DXT/RGTC) — 4×4 blocks
+    case "bc1-rgba-unorm": case "bc1-rgba-unorm-srgb":
+    case "bc4-r-unorm":   case "bc4-r-snorm":
+      return { width: 4, height: 4, bytesPerBlock: 8 };
+    case "bc2-rgba-unorm": case "bc2-rgba-unorm-srgb":
+    case "bc3-rgba-unorm": case "bc3-rgba-unorm-srgb":
+    case "bc5-rg-unorm":   case "bc5-rg-snorm":
+    case "bc6h-rgb-ufloat": case "bc6h-rgb-float":
+    case "bc7-rgba-unorm":  case "bc7-rgba-unorm-srgb":
+      return { width: 4, height: 4, bytesPerBlock: 16 };
+
+    // ETC2 — 4×4 blocks
+    case "etc2-rgb8unorm": case "etc2-rgb8unorm-srgb":
+    case "etc2-rgb8a1unorm": case "etc2-rgb8a1unorm-srgb":
+    case "eac-r11unorm":  case "eac-r11snorm":
+      return { width: 4, height: 4, bytesPerBlock: 8 };
+    case "etc2-rgba8unorm": case "etc2-rgba8unorm-srgb":
+    case "eac-rg11unorm":  case "eac-rg11snorm":
+      return { width: 4, height: 4, bytesPerBlock: 16 };
+
+    // ASTC — variable block size, all 16 bytes/block.
+    case "astc-4x4-unorm":   case "astc-4x4-unorm-srgb":   return { width: 4,  height: 4,  bytesPerBlock: 16 };
+    case "astc-5x4-unorm":   case "astc-5x4-unorm-srgb":   return { width: 5,  height: 4,  bytesPerBlock: 16 };
+    case "astc-5x5-unorm":   case "astc-5x5-unorm-srgb":   return { width: 5,  height: 5,  bytesPerBlock: 16 };
+    case "astc-6x5-unorm":   case "astc-6x5-unorm-srgb":   return { width: 6,  height: 5,  bytesPerBlock: 16 };
+    case "astc-6x6-unorm":   case "astc-6x6-unorm-srgb":   return { width: 6,  height: 6,  bytesPerBlock: 16 };
+    case "astc-8x5-unorm":   case "astc-8x5-unorm-srgb":   return { width: 8,  height: 5,  bytesPerBlock: 16 };
+    case "astc-8x6-unorm":   case "astc-8x6-unorm-srgb":   return { width: 8,  height: 6,  bytesPerBlock: 16 };
+    case "astc-8x8-unorm":   case "astc-8x8-unorm-srgb":   return { width: 8,  height: 8,  bytesPerBlock: 16 };
+    case "astc-10x5-unorm":  case "astc-10x5-unorm-srgb":  return { width: 10, height: 5,  bytesPerBlock: 16 };
+    case "astc-10x6-unorm":  case "astc-10x6-unorm-srgb":  return { width: 10, height: 6,  bytesPerBlock: 16 };
+    case "astc-10x8-unorm":  case "astc-10x8-unorm-srgb":  return { width: 10, height: 8,  bytesPerBlock: 16 };
+    case "astc-10x10-unorm": case "astc-10x10-unorm-srgb": return { width: 10, height: 10, bytesPerBlock: 16 };
+    case "astc-12x10-unorm": case "astc-12x10-unorm-srgb": return { width: 12, height: 10, bytesPerBlock: 16 };
+    case "astc-12x12-unorm": case "astc-12x12-unorm-srgb": return { width: 12, height: 12, bytesPerBlock: 16 };
+
+    default:
+      throw new Error(`blockInfoFor: unsupported format ${format}`);
+  }
+}
+
+/**
+ * Wrap an `aval<ITexture>` as a ref-counted, adaptively-uploaded
+ * `AdaptiveResource<GPUTexture>`.
+ */
+export function prepareAdaptiveTexture(
+  device: GPUDevice,
+  source: aval<ITexture>,
+  opts: PrepareAdaptiveTextureOptions = {},
+): AdaptiveResource<GPUTexture> {
+  return new AdaptiveTexture(device, source, opts);
+}

package/src/resources/framebuffer.ts

@@ -0,0 +1,163 @@
+// allocateFramebuffer — `aval<{width,height}>` → `AdaptiveResource<IFramebuffer>`.
+//
+// The signature defines names + formats; the size aval drives
+// allocation. Each color attachment gets its own GPUTexture sized
+// to the current `width × height`; depth/stencil similarly. On
+// size change, all textures are torn down and reallocated.
+//
+// This is the building block for `runtime.renderTo(scene, size)`:
+//   - The render task acquires the framebuffer's resource;
+//   - Each frame, evaluates the FBO via its own AdaptiveResource
+//     pipeline, getting current views;
+//   - Encodes a render pass into those views;
+//   - Exposes the chosen color attachment as an
+//     `aval<ITexture>` so downstream samplers see live data.
+
+import { AdaptiveResource, type IFramebuffer } from "../core/index.js";
+import { HashMap, type AdaptiveToken, type aval } from "@aardworx/wombat.adaptive";
+import { TextureUsage } from "./webgpuFlags.js";
+
+export interface FramebufferSize {
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface AllocateFramebufferOptions {
+  /** Extra usage flags ORed into every attachment. `RENDER_ATTACHMENT` is added automatically. */
+  readonly extraUsage?: GPUTextureUsageFlags;
+  /** Optional debug-label prefix; attachment name is appended. */
+  readonly labelPrefix?: string;
+}
+
+class AdaptiveFramebuffer extends AdaptiveResource<IFramebuffer> {
+  private _ownedColors = new Map<string, GPUTexture>();
+  private _ownedResolves = new Map<string, GPUTexture>();
+  private _ownedDepth: GPUTexture | undefined;
+  private _lastSize: FramebufferSize | undefined;
+
+  constructor(
+    private readonly device: GPUDevice,
+    private readonly signature: import("../core/index.js").FramebufferSignature,
+    private readonly size: aval<FramebufferSize>,
+    private readonly opts: AllocateFramebufferOptions,
+  ) {
+    super();
+  }
+
+  protected create(): void {}
+
+  protected destroy(): void {
+    for (const t of this._ownedColors.values()) t.destroy();
+    this._ownedColors.clear();
+    for (const t of this._ownedResolves.values()) t.destroy();
+    this._ownedResolves.clear();
+    if (this._ownedDepth !== undefined) {
+      this._ownedDepth.destroy();
+      this._ownedDepth = undefined;
+    }
+    this._lastSize = undefined;
+  }
+
+  override compute(token: AdaptiveToken): IFramebuffer {
+    const size = this.size.getValue(token);
+    if (
+      this._lastSize === undefined
+      || this._lastSize.width !== size.width
+      || this._lastSize.height !== size.height
+    ) {
+      this.reallocate(size);
+      this._lastSize = size;
+    }
+    const msaa = this.signature.sampleCount > 1;
+    let colorViews = HashMap.empty<string, GPUTextureView>();
+    let colorTextures = HashMap.empty<string, GPUTexture>();
+    let resolveViews = HashMap.empty<string, GPUTextureView>();
+    for (const [name, tex] of this._ownedColors.entries()) {
+      colorViews = colorViews.add(name, tex.createView());
+      if (msaa) {
+        const resolve = this._ownedResolves.get(name);
+        if (resolve === undefined) {
+          throw new Error(`framebuffer: missing resolve target for "${name}"`);
+        }
+        resolveViews = resolveViews.add(name, resolve.createView());
+        colorTextures = colorTextures.add(name, resolve);
+      } else {
+        colorTextures = colorTextures.add(name, tex);
+      }
+    }
+    return {
+      signature: this.signature,
+      colors: colorViews,
+      colorTextures,
+      ...(msaa ? { resolveColors: resolveViews } : {}),
+      ...(this._ownedDepth ? { depthStencil: this._ownedDepth.createView(), depthStencilTexture: this._ownedDepth } : {}),
+      width: size.width,
+      height: size.height,
+    };
+  }
+
+  private reallocate(size: FramebufferSize): void {
+    // Destroy old.
+    for (const t of this._ownedColors.values()) t.destroy();
+    this._ownedColors.clear();
+    for (const t of this._ownedResolves.values()) t.destroy();
+    this._ownedResolves.clear();
+    if (this._ownedDepth !== undefined) {
+      this._ownedDepth.destroy();
+      this._ownedDepth = undefined;
+    }
+    const sampleCount = this.signature.sampleCount;
+    const msaa = sampleCount > 1;
+    // Multisample textures are not directly sampleable; they only
+    // serve as render attachments, with a separate single-sample
+    // resolve target carrying TEXTURE_BINDING.
+    const colorUsage = msaa
+      ? TextureUsage.RENDER_ATTACHMENT
+      : TextureUsage.RENDER_ATTACHMENT
+        | TextureUsage.TEXTURE_BINDING
+        | (this.opts.extraUsage ?? 0);
+    const resolveUsage = TextureUsage.RENDER_ATTACHMENT
+      | TextureUsage.TEXTURE_BINDING
+      | (this.opts.extraUsage ?? 0);
+    const labelPrefix = this.opts.labelPrefix ?? "fbo";
+
+    for (const [name, format] of this.signature.colors) {
+      const tex = this.device.createTexture({
+        size: { width: size.width, height: size.height, depthOrArrayLayers: 1 },
+        format,
+        usage: colorUsage,
+        sampleCount,
+        label: msaa ? `${labelPrefix}.${name}.msaa` : `${labelPrefix}.${name}`,
+      });
+      this._ownedColors.set(name, tex);
+      if (msaa) {
+        const resolve = this.device.createTexture({
+          size: { width: size.width, height: size.height, depthOrArrayLayers: 1 },
+          format,
+          usage: resolveUsage,
+          sampleCount: 1,
+          label: `${labelPrefix}.${name}.resolve`,
+        });
+        this._ownedResolves.set(name, resolve);
+      }
+    }
+    if (this.signature.depthStencil !== undefined) {
+      this._ownedDepth = this.device.createTexture({
+        size: { width: size.width, height: size.height, depthOrArrayLayers: 1 },
+        format: this.signature.depthStencil.format,
+        usage: TextureUsage.RENDER_ATTACHMENT,
+        sampleCount,
+        label: `${labelPrefix}.depthStencil`,
+      });
+    }
+  }
+}
+
+export function allocateFramebuffer(
+  device: GPUDevice,
+  signature: import("../core/index.js").FramebufferSignature,
+  size: aval<FramebufferSize>,
+  opts: AllocateFramebufferOptions = {},
+): AdaptiveResource<IFramebuffer> {
+  return new AdaptiveFramebuffer(device, signature, size, opts);
+}

package/src/resources/framebufferSignature.ts

@@ -0,0 +1,36 @@
+// Helpers for constructing a `FramebufferSignature` from plain
+// records. Pure value construction — no GPU calls — but lives in
+// the resources package because it pairs with `allocateFramebuffer`.
+
+import { HashMap } from "@aardworx/wombat.adaptive";
+import type {
+  DepthStencilAttachmentSignature,
+  FramebufferSignature,
+} from "../core/index.js";
+
+export interface FramebufferSignatureSpec {
+  readonly colors: Record<string, GPUTextureFormat>;
+  readonly depthStencil?: { readonly format: GPUTextureFormat };
+  readonly sampleCount?: number;
+}
+
+export function createFramebufferSignature(
+  spec: FramebufferSignatureSpec,
+): FramebufferSignature {
+  let colors = HashMap.empty<string, GPUTextureFormat>();
+  for (const [name, format] of Object.entries(spec.colors)) {
+    colors = colors.add(name, format);
+  }
+  const sig: FramebufferSignature = {
+    colors,
+    sampleCount: spec.sampleCount ?? 1,
+    ...(spec.depthStencil ? { depthStencil: depthStencilFor(spec.depthStencil.format) } : {}),
+  };
+  return sig;
+}
+
+function depthStencilFor(format: GPUTextureFormat): DepthStencilAttachmentSignature {
+  const hasDepth = /^depth/.test(format) || format === "depth24plus-stencil8" || format === "depth32float-stencil8";
+  const hasStencil = /stencil/.test(format);
+  return { format, hasDepth, hasStencil };
+}

package/src/resources/index.ts

@@ -0,0 +1,82 @@
+// Public API of @aardworx/wombat.rendering-resources.
+//
+// Layer 2 — resource-creator functions on `GPUDevice`. Each
+// `prepare*` function lifts a user-provided `aval<I…>` source
+// type into a ref-counted `AdaptiveResource<GPU…>` that:
+//   - Allocates the GPU handle on first compute / on host
+//     mismatch.
+//   - Uploads on host-side change, reuses the existing handle
+//     when shape-compatible.
+//   - Frees the handle on last `release()`.
+
+export {
+  prepareAdaptiveBuffer,
+  type PrepareAdaptiveBufferOptions,
+} from "./adaptiveBuffer.js";
+
+export {
+  prepareAdaptiveTexture,
+  type PrepareAdaptiveTextureOptions,
+} from "./adaptiveTexture.js";
+
+export {
+  prepareAdaptiveSampler,
+} from "./adaptiveSampler.js";
+
+export {
+  prepareUniformBuffer,
+  type PrepareUniformBufferOptions,
+} from "./uniformBuffer.js";
+
+export {
+  compileRenderPipeline,
+  type CompileRenderPipelineDescription,
+} from "./renderPipeline.js";
+
+export {
+  installShaderDiagnostics,
+  type ShaderDiagnosticsOptions,
+} from "./shaderDiagnostics.js";
+
+export {
+  decodeLine,
+  decodePosition,
+  type DecodedPosition,
+} from "./sourceMapDecoder.js";
+
+export {
+  generateMips,
+  type GenerateMipsOptions,
+} from "./mipGen.js";
+
+export {
+  prepareRenderObject,
+  PreparedRenderObject,
+  type PrepareRenderObjectOptions,
+} from "./preparedRenderObject.js";
+
+export {
+  prepareComputeShader,
+  PreparedComputeShader,
+  ComputeInputBinding,
+  type PrepareComputeShaderOptions,
+  type DispatchSize,
+} from "./preparedComputeShader.js";
+
+export {
+  createFramebufferSignature,
+  type FramebufferSignatureSpec,
+} from "./framebufferSignature.js";
+
+export {
+  allocateFramebuffer,
+  type AllocateFramebufferOptions,
+  type FramebufferSize,
+} from "./framebuffer.js";
+
+export {
+  BufferUsage,
+  ColorWrite,
+  ShaderStage,
+  TextureUsage,
+} from "./webgpuFlags.js";

package/src/resources/mipGen.ts

@@ -0,0 +1,148 @@
+// Mip-map generation via compute pass.
+//
+// Standard 2× downsample shader: each invocation reads a 2×2 block
+// of source-mip texels and writes the average to the destination
+// mip. Iterated mip(N) → mip(N+1) for each pair of adjacent levels.
+//
+// `generateMips(device, encoder, texture)` records the dispatches
+// into the encoder; the user is responsible for submission.
+// Pipelines + bind groups are cached per (device, format) so
+// repeat calls share the GPU work.
+
+const WGSL_MIP_GEN_TEMPLATE = (storageFormat: string) => `
+@group(0) @binding(0) var src: texture_2d<f32>;
+@group(0) @binding(1) var dst: texture_storage_2d<${storageFormat}, write>;
+
+@compute @workgroup_size(8, 8, 1)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    let dstSize: vec2<u32> = textureDimensions(dst);
+    if (id.x >= dstSize.x || id.y >= dstSize.y) { return; }
+    let srcSize: vec2<u32> = textureDimensions(src);
+    let i: vec2<i32> = vec2<i32>(i32(id.x) * 2, i32(id.y) * 2);
+    let i2: vec2<i32> = vec2<i32>(min(i.x + 1, i32(srcSize.x) - 1), min(i.y + 1, i32(srcSize.y) - 1));
+    let a: vec4<f32> = textureLoad(src, vec2<i32>(i.x,  i.y),  0);
+    let b: vec4<f32> = textureLoad(src, vec2<i32>(i2.x, i.y),  0);
+    let c: vec4<f32> = textureLoad(src, vec2<i32>(i.x,  i2.y), 0);
+    let d: vec4<f32> = textureLoad(src, vec2<i32>(i2.x, i2.y), 0);
+    textureStore(dst, vec2<i32>(i32(id.x), i32(id.y)), (a + b + c + d) * 0.25);
+}
+`;
+
+interface MipPipelineCache {
+  pipelines: Map<GPUTextureFormat, { pipeline: GPUComputePipeline; layout: GPUBindGroupLayout }>;
+}
+
+const caches = new WeakMap<GPUDevice, MipPipelineCache>();
+
+function pipelineFor(device: GPUDevice, format: GPUTextureFormat): { pipeline: GPUComputePipeline; layout: GPUBindGroupLayout } {
+  let cache = caches.get(device);
+  if (cache === undefined) {
+    cache = { pipelines: new Map() };
+    caches.set(device, cache);
+  }
+  const existing = cache.pipelines.get(format);
+  if (existing !== undefined) return existing;
+
+  const storageFormat = storageFormatFor(format);
+  const module = device.createShaderModule({ code: WGSL_MIP_GEN_TEMPLATE(storageFormat), label: `mipgen-${format}` });
+  const layout = device.createBindGroupLayout({
+    entries: [
+      { binding: 0, visibility: 0x4, texture: { sampleType: "float" } },
+      { binding: 1, visibility: 0x4, storageTexture: { access: "write-only", format: storageFormat as GPUTextureFormat } },
+    ],
+  });
+  const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [layout] });
+  const pipeline = device.createComputePipeline({
+    layout: pipelineLayout,
+    compute: { module, entryPoint: "main" },
+    label: `mipgen-${format}`,
+  });
+  const entry = { pipeline, layout };
+  cache.pipelines.set(format, entry);
+  return entry;
+}
+
+/**
+ * WebGPU storage-texture formats are a constrained subset; we map
+ * common sampled formats to the closest writable storage format.
+ * For BGRA / sRGB / non-storage formats we fall back to
+ * `rgba8unorm` and accept the colour-space caveat (callers using
+ * sRGB textures should generate their mips in linear).
+ */
+function storageFormatFor(format: GPUTextureFormat): GPUTextureFormat {
+  switch (format) {
+    case "rgba8unorm":
+    case "rgba8snorm":
+    case "rgba16float":
+    case "rgba32float":
+    case "r32float":
+    case "rg32float":
+    case "r32uint":
+    case "rg32uint":
+    case "rgba32uint":
+      return format;
+    default:
+      return "rgba8unorm";
+  }
+}
+
+export interface GenerateMipsOptions {
+  /** Generate mips starting from this base level. Default 0. */
+  readonly baseMipLevel?: number;
+  /** Generate up to this many additional mips beyond the base. Default: down to 1×1. */
+  readonly mipLevelCount?: number;
+  /** Optional debug label. */
+  readonly label?: string;
+}
+
+/**
+ * Records compute dispatches that downsample `texture`'s mip
+ * chain. The texture must have been created with
+ * `STORAGE_BINDING | TEXTURE_BINDING` and the appropriate
+ * `mipLevelCount`. Each level is computed from the level above
+ * via a 2×2 box filter.
+ */
+export function generateMips(
+  device: GPUDevice,
+  encoder: GPUCommandEncoder,
+  texture: GPUTexture,
+  opts: GenerateMipsOptions = {},
+): void {
+  const baseLevel = opts.baseMipLevel ?? 0;
+  const totalMips = texture.mipLevelCount;
+  const lastLevel = opts.mipLevelCount !== undefined
+    ? Math.min(totalMips - 1, baseLevel + opts.mipLevelCount)
+    : totalMips - 1;
+  if (lastLevel <= baseLevel) return;
+
+  const { pipeline, layout } = pipelineFor(device, texture.format);
+  const pass = encoder.beginComputePass(opts.label !== undefined ? { label: opts.label } : {});
+  pass.setPipeline(pipeline);
+
+  for (let mip = baseLevel; mip < lastLevel; mip++) {
+    const dstWidth = Math.max(1, texture.width >> (mip + 1));
+    const dstHeight = Math.max(1, texture.height >> (mip + 1));
+    const srcView = texture.createView({
+      baseMipLevel: mip, mipLevelCount: 1,
+      baseArrayLayer: 0, arrayLayerCount: 1,
+      dimension: "2d",
+    });
+    const dstView = texture.createView({
+      baseMipLevel: mip + 1, mipLevelCount: 1,
+      baseArrayLayer: 0, arrayLayerCount: 1,
+      dimension: "2d",
+    });
+    const bg = device.createBindGroup({
+      layout,
+      entries: [
+        { binding: 0, resource: srcView },
+        { binding: 1, resource: dstView },
+      ],
+    });
+    pass.setBindGroup(0, bg);
+    const workX = Math.ceil(dstWidth / 8);
+    const workY = Math.ceil(dstHeight / 8);
+    pass.dispatchWorkgroups(workX, workY, 1);
+  }
+  pass.end();
+}