@aardworx/wombat.rendering 0.1.0

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@aardworx/wombat.rendering",
+  "version": "0.1.0",
+  "description": "WebGPU rendering layer for the Wombat TypeScript stack — RenderObject/RenderTask/runtime + window glue, port of Aardvark.Rendering's lower layers on top of WebGPU and wombat.shader.",
+  "license": "MIT",
+  "author": "krauthaufen",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/krauthaufen/wombat.rendering.git"
+  },
+  "homepage": "https://github.com/krauthaufen/wombat.rendering",
+  "keywords": [
+    "wombat",
+    "aardvark",
+    "webgpu",
+    "rendering",
+    "renderobject",
+    "rendertask",
+    "scenegraph",
+    "shader"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    },
+    "./resources": {
+      "types": "./dist/resources/index.d.ts",
+      "import": "./dist/resources/index.js"
+    },
+    "./commands": {
+      "types": "./dist/commands/index.d.ts",
+      "import": "./dist/commands/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
+    "./window": {
+      "types": "./dist/window/index.d.ts",
+      "import": "./dist/window/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@aardworx/wombat.adaptive": "^0.2.1",
+    "@aardworx/wombat.base": "^0.3.0",
+    "@aardworx/wombat.shader": "^0.2.1"
+  },
+  "devDependencies": {
+    "@webgpu/types": "^0.1.69"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/commands/clear.ts

@@ -0,0 +1,66 @@
+// clear(cmd, output, values) — open a render pass on `output`
+// with `loadOp: "clear"` for the named attachments listed in
+// `values`, and `loadOp: "load"` for the rest. End the pass
+// immediately. This is the encoding for a `Clear` Command.
+//
+// Note that color clears are typed as `V4f | V4i | V4ui`; we
+// translate to WebGPU's `GPUColorDict` (always `r/g/b/a` numbers)
+// directly. WebGPU figures out the integer-vs-float interpretation
+// from the texture's format.
+
+import type { ClearValues, IFramebuffer } from "../core/index.js";
+
+export function clear(
+  cmd: GPUCommandEncoder,
+  output: IFramebuffer,
+  values: ClearValues,
+): void {
+  const colorAttachments: GPURenderPassColorAttachment[] = [];
+  for (const [name] of output.signature.colors) {
+    const view = output.colors.tryFind(name);
+    if (view === undefined) {
+      throw new Error(`clear: framebuffer is missing color attachment "${name}"`);
+    }
+    const cv = values.colors?.tryFind(name);
+    if (cv !== undefined) {
+      const d = cv as unknown as { _data: ArrayLike<number> };
+      colorAttachments.push({
+        view,
+        loadOp: "clear",
+        storeOp: "store",
+        clearValue: { r: d._data[0]!, g: d._data[1]!, b: d._data[2]!, a: d._data[3]! },
+      });
+    } else {
+      colorAttachments.push({ view, loadOp: "load", storeOp: "store" });
+    }
+  }
+  let depthStencilAttachment: GPURenderPassDepthStencilAttachment | undefined;
+  if (output.signature.depthStencil !== undefined) {
+    if (output.depthStencil === undefined) {
+      throw new Error("clear: signature has depthStencil but framebuffer.depthStencil is undefined");
+    }
+    const sig = output.signature.depthStencil;
+    const att: GPURenderPassDepthStencilAttachment = { view: output.depthStencil };
+    if (sig.hasDepth) {
+      if (values.depth !== undefined) {
+        att.depthLoadOp = "clear"; att.depthStoreOp = "store"; att.depthClearValue = values.depth;
+      } else {
+        att.depthLoadOp = "load"; att.depthStoreOp = "store";
+      }
+    }
+    if (sig.hasStencil) {
+      if (values.stencil !== undefined) {
+        att.stencilLoadOp = "clear"; att.stencilStoreOp = "store"; att.stencilClearValue = values.stencil;
+      } else {
+        att.stencilLoadOp = "load"; att.stencilStoreOp = "store";
+      }
+    }
+    depthStencilAttachment = att;
+  }
+  const desc: GPURenderPassDescriptor = {
+    colorAttachments,
+    ...(depthStencilAttachment !== undefined ? { depthStencilAttachment } : {}),
+  };
+  const pass = cmd.beginRenderPass(desc);
+  pass.end();
+}

package/src/commands/index.ts

@@ -0,0 +1,11 @@
+// Public API of @aardworx/wombat.rendering-commands.
+// Layer 3 — command-stream functions on `GPUCommandEncoder`.
+
+export { clear } from "./clear.js";
+
+export {
+  render,
+  renderMany,
+  beginPassDescriptor,
+  type Recordable,
+} from "./render.js";

package/src/commands/render.ts

@@ -0,0 +1,106 @@
+// render(cmd, prepared, output, token) — open a render pass on
+// `output` (loadOp = "load"; clears go through the `Clear` command),
+// record the prepared object, end the pass.
+//
+// Multiple prepared objects can be batched into one pass via
+// `renderMany(...)` — same pass, multiple `record` calls — which
+// is the path the RenderTask walker uses for an `Ordered` /
+// `Unordered` subtree of leaves all targeting the same FBO.
+
+import type { ClearValues, IFramebuffer } from "../core/index.js";
+import type { AdaptiveToken } from "@aardworx/wombat.adaptive";
+
+// Forward type — we don't import from -resources to avoid a
+// commands→resources dependency cycle. Anyone constructing a
+// PreparedRenderObject hands it to us; we only call `record`.
+export interface Recordable {
+  record(pass: GPURenderPassEncoder, token: AdaptiveToken): void;
+}
+
+/**
+ * Build a render-pass descriptor for `output`. If `clear` is set,
+ * named attachments use `loadOp: "clear"` with the requested
+ * values; the rest fall back to `loadOp: "load"`. Used by
+ * `render` / `renderMany` and by the runtime walker's Clear+Render
+ * coalescing path.
+ */
+export function beginPassDescriptor(output: IFramebuffer, clear?: ClearValues): GPURenderPassDescriptor {
+  const colorAttachments: GPURenderPassColorAttachment[] = [];
+  const msaa = output.signature.sampleCount > 1;
+  for (const [name] of output.signature.colors) {
+    const view = output.colors.tryFind(name);
+    if (view === undefined) {
+      throw new Error(`render: framebuffer is missing color attachment "${name}"`);
+    }
+    const resolveTarget = msaa ? output.resolveColors?.tryFind(name) : undefined;
+    if (msaa && resolveTarget === undefined) {
+      throw new Error(`render: MSAA framebuffer is missing resolve target for "${name}"`);
+    }
+    const cv = clear?.colors?.tryFind(name);
+    if (cv !== undefined) {
+      const d = cv as unknown as { _data: ArrayLike<number> };
+      colorAttachments.push({
+        view, loadOp: "clear", storeOp: "store",
+        ...(resolveTarget !== undefined ? { resolveTarget } : {}),
+        clearValue: { r: d._data[0]!, g: d._data[1]!, b: d._data[2]!, a: d._data[3]! },
+      });
+    } else {
+      colorAttachments.push({
+        view, loadOp: "load", storeOp: "store",
+        ...(resolveTarget !== undefined ? { resolveTarget } : {}),
+      });
+    }
+  }
+  let depthStencilAttachment: GPURenderPassDepthStencilAttachment | undefined;
+  if (output.signature.depthStencil !== undefined) {
+    if (output.depthStencil === undefined) {
+      throw new Error("render: signature has depthStencil but framebuffer.depthStencil is undefined");
+    }
+    const sig = output.signature.depthStencil;
+    const att: GPURenderPassDepthStencilAttachment = { view: output.depthStencil };
+    if (sig.hasDepth) {
+      if (clear?.depth !== undefined) {
+        att.depthLoadOp = "clear"; att.depthStoreOp = "store"; att.depthClearValue = clear.depth;
+      } else {
+        att.depthLoadOp = "load"; att.depthStoreOp = "store";
+      }
+    }
+    if (sig.hasStencil) {
+      if (clear?.stencil !== undefined) {
+        att.stencilLoadOp = "clear"; att.stencilStoreOp = "store"; att.stencilClearValue = clear.stencil;
+      } else {
+        att.stencilLoadOp = "load"; att.stencilStoreOp = "store";
+      }
+    }
+    depthStencilAttachment = att;
+  }
+  return {
+    colorAttachments,
+    ...(depthStencilAttachment !== undefined ? { depthStencilAttachment } : {}),
+  };
+}
+
+export function render(
+  cmd: GPUCommandEncoder,
+  prepared: Recordable,
+  output: IFramebuffer,
+  token: AdaptiveToken,
+  clear?: ClearValues,
+): void {
+  const pass = cmd.beginRenderPass(beginPassDescriptor(output, clear));
+  prepared.record(pass, token);
+  pass.end();
+}
+
+export function renderMany(
+  cmd: GPUCommandEncoder,
+  prepared: readonly Recordable[],
+  output: IFramebuffer,
+  token: AdaptiveToken,
+  clear?: ClearValues,
+): void {
+  if (prepared.length === 0) return;
+  const pass = cmd.beginRenderPass(beginPassDescriptor(output, clear));
+  for (const p of prepared) p.record(pass, token);
+  pass.end();
+}

package/src/core/acquire.ts

@@ -0,0 +1,22 @@
+// tryAcquire / tryRelease — propagate acquire/release through
+// the dependency graph. If a value is an `AdaptiveResource`, drive
+// its lifetime; otherwise no-op. Used by wrapper resources
+// (`prepareAdaptiveBuffer`, `prepareAdaptiveTexture`, …) so that
+// when a downstream consumer acquires them, any upstream
+// AdaptiveResources they read also get acquired.
+//
+// This is what makes `renderTo` work: the returned `aval<ITexture>`
+// is an AdaptiveResource holding an FBO + inner RenderTask. When
+// a downstream RenderObject's prepareAdaptiveTexture acquires its
+// source, that source is the renderTo result, and the FBO + task
+// come live automatically.
+
+import { AdaptiveResource } from "./adaptiveResource.js";
+
+export function tryAcquire(av: unknown): void {
+  if (av instanceof AdaptiveResource) av.acquire();
+}
+
+export function tryRelease(av: unknown): void {
+  if (av instanceof AdaptiveResource) av.release();
+}

package/src/core/adaptiveResource.ts

@@ -0,0 +1,88 @@
+// AdaptiveResource<T> — a ref-counted, adaptively-updated GPU
+// handle that **is itself an `aval<T>`**. Lifted directly from
+// Aardvark.Base's `AdaptiveResource<'a>`.
+//
+// The shape lets `runtime.renderTo(scene, size) → aval<ITexture>`
+// work the way Aardvark.Rendering's `RenderTask.renderTo` works:
+// a downstream consumer treats it like any other `aval<ITexture>`,
+// the FBO is allocated lazily on first `acquire`, and torn down
+// when the last consumer releases.
+//
+// Lifecycle:
+//   acquire()  — refCount++. On 0→1 transition, calls `create()`,
+//                which is where one-time setup happens (allocate
+//                an FBO, register input subscriptions, etc.).
+//   getValue(token) — the standard aval contract. Calls
+//                `compute(token)`, which is where adaptive work
+//                lives (re-render scene if size or scene changed,
+//                return the texture handle). May encode commands
+//                on the currently-active `RenderContext.encoder`.
+//   release()  — refCount--. On 1→0 transition, calls `destroy()`,
+//                which frees the GPU resources.
+//
+// Subscribing to value changes (`addCallback`) does **not** acquire
+// — acquisition is an explicit lifetime concern and a subscription
+// alone does not justify keeping GPU memory live. The runtime's
+// RenderTask compilation walks its referenced AdaptiveResources
+// and acquires them at task-construction time, releases them on
+// task disposal.
+
+import {
+  AbstractVal,
+  type AdaptiveToken,
+} from "@aardworx/wombat.adaptive";
+
+export abstract class AdaptiveResource<T> extends AbstractVal<T> {
+  private _refCount = 0;
+
+  /** Allocate one-time GPU resources. Called on the 0→1 acquire. */
+  protected abstract create(): void;
+  /** Free GPU resources. Called on the 1→0 release. */
+  protected abstract destroy(): void;
+  /**
+   * The standard aval contract: produce the current handle for
+   * this resource. May read other adaptive inputs via `token` and
+   * may encode work onto `RenderContext.encoder` if one is active
+   * (uploads, compute dispatches, render-to-texture, ...).
+   */
+  abstract override compute(token: AdaptiveToken): T;
+
+  acquire(): void {
+    this._refCount++;
+    if (this._refCount === 1) this.create();
+  }
+
+  release(): void {
+    if (this._refCount <= 0) {
+      throw new Error("AdaptiveResource: release without matching acquire");
+    }
+    this._refCount--;
+    if (this._refCount === 0) this.destroy();
+  }
+
+  /** True iff at least one consumer holds an acquire. */
+  get isActive(): boolean { return this._refCount > 0; }
+  get refCount(): number { return this._refCount; }
+
+  /**
+   * Derive a new `AdaptiveResource<R>` whose lifetime forwards to
+   * `this`. Consumers of the derived resource transitively
+   * acquire/release `this`. Use this to expose structured outputs
+   * of a complex resource (e.g. the colour textures of a `renderTo`
+   * framebuffer) as individual `aval<ITexture>`s.
+   */
+  derive<R>(project: (t: T) => R): AdaptiveResource<R> {
+    return new DerivedAdaptiveResource<T, R>(this, project);
+  }
+}
+
+class DerivedAdaptiveResource<T, R> extends AdaptiveResource<R> {
+  constructor(private readonly parent: AdaptiveResource<T>, private readonly project: (t: T) => R) {
+    super();
+  }
+  protected override create(): void { this.parent.acquire(); }
+  protected override destroy(): void { this.parent.release(); }
+  override compute(token: AdaptiveToken): R {
+    return this.project(this.parent.getValue(token));
+  }
+}

package/src/core/buffer.ts

@@ -0,0 +1,45 @@
+// IBuffer — a buffer source that can be either a real GPU buffer
+// or host-side memory (an ArrayBuffer, a TypedArray, or a packed
+// view from wombat.base such as `V2fArray._data` or `arr.buffer`).
+//
+// The user is free to mix and match: an `aval<IBuffer>` can flip
+// between `gpu` and `host` over its lifetime, and the rendering
+// layer transparently handles the upload when a `host` value is
+// observed.
+//
+// `host.data` is typed as `BufferSource` (DOM standard) which
+// admits `ArrayBuffer`, `SharedArrayBuffer`, and any
+// `ArrayBufferView` — covering wombat.base's packed array views
+// that expose a `.buffer` (ArrayBuffer) or a typed array directly.
+
+export type HostBufferSource = ArrayBuffer | ArrayBufferView;
+
+export type IBuffer =
+  | {
+      readonly kind: "gpu";
+      readonly buffer: GPUBuffer;
+      readonly sizeBytes: number;
+    }
+  | {
+      readonly kind: "host";
+      readonly data: HostBufferSource;
+      readonly sizeBytes: number;
+    };
+
+export const IBuffer = {
+  fromGPU(buffer: GPUBuffer, sizeBytes?: number): IBuffer {
+    return { kind: "gpu", buffer, sizeBytes: sizeBytes ?? buffer.size };
+  },
+  /**
+   * Wrap a host-side `ArrayBuffer` / `ArrayBufferView`. Pass any
+   * wombat.base packed array's `.buffer` directly, or a `Float32Array`,
+   * etc.
+   */
+  fromHost(data: HostBufferSource): IBuffer {
+    const sizeBytes =
+      data instanceof ArrayBuffer
+        ? data.byteLength
+        : data.byteLength;
+    return { kind: "host", data, sizeBytes };
+  },
+} as const;

package/src/core/bufferView.ts

@@ -0,0 +1,26 @@
+// BufferView — a typed slice of an `IBuffer` used as a vertex
+// attribute, instance attribute, or index source. The buffer
+// itself can be a real GPU buffer or host-side memory; the
+// runtime handles upload transparently.
+//
+// `format` carries the WebGPU vertex format when this view is
+// bound as a vertex / instance attribute. `indexFormat` is set
+// when the view is bound as an index buffer; in that case
+// `format` is ignored. Both are optional so callers don't have
+// to fill in the irrelevant one.
+
+import type { IBuffer } from "./buffer.js";
+
+export interface BufferView {
+  readonly buffer: IBuffer;
+  /** Byte offset into `buffer` where the view starts. */
+  readonly offset: number;
+  /** Number of elements (not bytes) in the view. */
+  readonly count: number;
+  /** Stride between consecutive elements, in bytes. */
+  readonly stride: number;
+  /** Vertex format — used when bound as a vertex / instance attribute. */
+  readonly format: GPUVertexFormat | GPUIndexFormat;
+  /** Index format — used when bound as an index buffer. Overrides `format`. */
+  readonly indexFormat?: GPUIndexFormat;
+}

package/src/core/clear.ts

@@ -0,0 +1,16 @@
+// ClearValues — per-attachment, name-keyed clear specification.
+// Color clears are typed as V4f / V4i / V4ui to match the
+// attachment's format; depth and stencil are plain numbers since
+// WebGPU's GPURenderPassDepthStencilAttachment takes scalars.
+// Attachments not named in `colors` keep their previous contents.
+
+import type { HashMap } from "@aardworx/wombat.adaptive";
+import type { V4f, V4i, V4ui } from "@aardworx/wombat.base";
+
+export type ClearColor = V4f | V4i | V4ui;
+
+export interface ClearValues {
+  readonly colors?: HashMap<string, ClearColor>;
+  readonly depth?: number;
+  readonly stencil?: number;
+}

package/src/core/command.ts

@@ -0,0 +1,50 @@
+// Command — the per-frame primitive consumed by `runtime.compile`.
+// Four kinds:
+//   Render: encode a RenderTree into an FBO.
+//   Clear:  clear individual named attachments of an FBO.
+//   Copy:   buffer↔buffer / texture↔texture transfers.
+//   Custom: escape hatch — receives the raw GPUCommandEncoder.
+//
+// Compute and Upload are NOT commands; they live inside
+// AdaptiveResource update logic and run implicitly when a Render
+// command needs a dirty resource.
+
+import type { aval } from "@aardworx/wombat.adaptive";
+import type { ClearValues } from "./clear.js";
+import type { IFramebuffer } from "./framebuffer.js";
+import type { RenderTree } from "./renderTree.js";
+
+export interface BufferCopyRange {
+  readonly srcOffset: number;
+  readonly dstOffset: number;
+  readonly size: number;
+}
+
+export interface BufferCopy {
+  readonly kind: "buffer";
+  readonly src: GPUBuffer;
+  readonly dst: GPUBuffer;
+  readonly range?: BufferCopyRange;
+}
+
+export interface TextureCopy {
+  readonly kind: "texture";
+  readonly src: GPUImageCopyTexture;
+  readonly dst: GPUImageCopyTexture;
+  readonly size: GPUExtent3DStrict;
+}
+
+export type CopySpec = BufferCopy | TextureCopy;
+
+/**
+ * `Render` and `Clear` take an `aval<IFramebuffer>` for their output
+ * so that swap-chain framebuffers (which produce a fresh
+ * `GPUTextureView` every animation frame) flow through cleanly.
+ * For static FBOs, wrap with `cval(...)` from `@aardworx/wombat.adaptive`
+ * — the runtime evaluates the aval per frame.
+ */
+export type Command =
+  | { readonly kind: "Render"; readonly output: aval<IFramebuffer>; readonly tree: RenderTree }
+  | { readonly kind: "Clear"; readonly output: aval<IFramebuffer>; readonly values: ClearValues }
+  | { readonly kind: "Copy"; readonly copy: CopySpec }
+  | { readonly kind: "Custom"; readonly encode: (cmd: GPUCommandEncoder) => void };

package/src/core/drawCall.ts

@@ -0,0 +1,22 @@
+// DrawCall — what to actually draw, once the pipeline + bindings
+// are bound. Indexed and non-indexed variants; both can be
+// instanced.
+
+export interface IndexedDrawCall {
+  readonly kind: "indexed";
+  readonly indexCount: number;
+  readonly instanceCount: number;
+  readonly firstIndex: number;
+  readonly baseVertex: number;
+  readonly firstInstance: number;
+}
+
+export interface NonIndexedDrawCall {
+  readonly kind: "non-indexed";
+  readonly vertexCount: number;
+  readonly instanceCount: number;
+  readonly firstVertex: number;
+  readonly firstInstance: number;
+}
+
+export type DrawCall = IndexedDrawCall | NonIndexedDrawCall;

package/src/core/framebuffer.ts

@@ -0,0 +1,37 @@
+// IFramebuffer — a concrete render target. The signature describes
+// the *shape*; the framebuffer pairs that shape with concrete
+// texture views. Both color and depth/stencil views are addressed
+// by the same names declared in the signature.
+
+import type { HashMap } from "@aardworx/wombat.adaptive";
+import type { FramebufferSignature } from "./framebufferSignature.js";
+
+export interface IFramebuffer {
+  readonly signature: FramebufferSignature;
+  /**
+   * name → color attachment view used inside the render pass.
+   * For `sampleCount > 1` these are views into the multisample
+   * textures; the resolve target views live in `resolveColors`.
+   */
+  readonly colors: HashMap<string, GPUTextureView>;
+  readonly depthStencil?: GPUTextureView;
+  /**
+   * Underlying GPU textures suitable for *sampling* downstream.
+   * - `sampleCount = 1`: same textures as `colors`.
+   * - `sampleCount > 1`: the resolve textures (single-sample);
+   *   the multisample textures are not sampleable.
+   * Populated by `allocateFramebuffer`; used by `renderTo` to
+   * expose results as `ITexture.fromGPU(...)`.
+   */
+  readonly colorTextures?: HashMap<string, GPUTexture>;
+  /**
+   * name → resolve target view, only present when
+   * `signature.sampleCount > 1`. Wired into the render pass
+   * descriptor as `resolveTarget` so the GPU resolves
+   * multisample → single-sample at end of pass.
+   */
+  readonly resolveColors?: HashMap<string, GPUTextureView>;
+  readonly depthStencilTexture?: GPUTexture;
+  readonly width: number;
+  readonly height: number;
+}

package/src/core/framebufferSignature.ts

@@ -0,0 +1,19 @@
+// FramebufferSignature — the typed shape of a render target.
+// Attachments are addressed by name (never by index). The runtime
+// maps names → WebGPU attachment slots using a shader's
+// ProgramInterface, so users only ever talk about names like
+// "albedo" / "normal" / "objectId", not location indices.
+
+import type { HashMap } from "@aardworx/wombat.adaptive";
+
+export interface DepthStencilAttachmentSignature {
+  readonly format: GPUTextureFormat;
+  readonly hasDepth: boolean;
+  readonly hasStencil: boolean;
+}
+
+export interface FramebufferSignature {
+  readonly colors: HashMap<string, GPUTextureFormat>;
+  readonly depthStencil?: DepthStencilAttachmentSignature;
+  readonly sampleCount: number;
+}