@aardworx/wombat.rendering 0.1.0

package/src/core/index.ts

@@ -0,0 +1,116 @@
+// Public API of @aardworx/wombat.rendering-core.
+//
+// Phase 0: types only. Implementations of `compileEffect`,
+// `prepareRenderObject`, `runRenderTask`, etc. live in higher
+// packages (`resources`, `commands`, `runtime`).
+
+export {
+  IBuffer,
+} from "./buffer.js";
+export type {
+  HostBufferSource,
+} from "./buffer.js";
+
+export type {
+  BufferView,
+} from "./bufferView.js";
+
+export type {
+  ClearColor,
+  ClearValues,
+} from "./clear.js";
+
+export type {
+  Command,
+  CopySpec,
+  BufferCopy,
+  TextureCopy,
+  BufferCopyRange,
+} from "./command.js";
+
+export type {
+  DrawCall,
+  IndexedDrawCall,
+  NonIndexedDrawCall,
+} from "./drawCall.js";
+
+export type {
+  IFramebuffer,
+} from "./framebuffer.js";
+
+export type {
+  DepthStencilAttachmentSignature,
+  FramebufferSignature,
+} from "./framebufferSignature.js";
+
+export type {
+  BlendComponentState,
+  BlendState,
+  CullMode,
+  DepthState,
+  FrontFace,
+  PipelineState,
+  RasterizerState,
+  StencilFaceState,
+  StencilState,
+  Topology,
+} from "./pipelineState.js";
+
+export type {
+  RenderObject,
+} from "./renderObject.js";
+
+export {
+  RenderTree,
+} from "./renderTree.js";
+
+export type {
+  IRenderTask,
+} from "./renderTask.js";
+
+export {
+  ISampler,
+} from "./sampler.js";
+
+export {
+  ITexture,
+} from "./texture.js";
+export type {
+  ExternalTextureSource,
+  HostTextureSource,
+  RawTextureSource,
+} from "./texture.js";
+
+export type {
+  AttributeInfo,
+  CompiledEffect,
+  CompiledStage,
+  ComputeShader,
+  Effect,
+  HoleGetter,
+  HoleGetters,
+  LooseUniformInfo,
+  OutputInfo,
+  ProgramInterface,
+  SamplerInfo,
+  Stage,
+  StageInfo,
+  StorageBufferInfo,
+  Target,
+  TextureInfo,
+  UniformBlockInfo,
+  UniformFieldInfo,
+} from "./shader.js";
+
+export {
+  AdaptiveResource,
+} from "./adaptiveResource.js";
+
+export {
+  tryAcquire,
+  tryRelease,
+} from "./acquire.js";
+
+export {
+  RenderContext,
+} from "./renderContext.js";

package/src/core/pipelineState.ts

@@ -0,0 +1,64 @@
+// PipelineState — the fixed-function bits the user picks per
+// RenderObject. Vertex layout, blending, depth/stencil, raster.
+// Combined with a CompiledEffect + FramebufferSignature this is
+// enough to bake a GPURenderPipeline.
+
+import type { HashMap } from "@aardworx/wombat.adaptive";
+
+export type CullMode = "none" | "front" | "back";
+export type FrontFace = "ccw" | "cw";
+export type Topology = GPUPrimitiveTopology;
+
+export interface RasterizerState {
+  readonly topology: Topology;
+  readonly cullMode: CullMode;
+  readonly frontFace: FrontFace;
+  /** "none" disables polygon offset. */
+  readonly depthBias?: { readonly constant: number; readonly slopeScale: number; readonly clamp: number };
+}
+
+export interface DepthState {
+  readonly write: boolean;
+  readonly compare: GPUCompareFunction;
+}
+
+export interface StencilFaceState {
+  readonly compare: GPUCompareFunction;
+  readonly failOp: GPUStencilOperation;
+  readonly depthFailOp: GPUStencilOperation;
+  readonly passOp: GPUStencilOperation;
+}
+
+export interface StencilState {
+  readonly readMask: number;
+  readonly writeMask: number;
+  readonly front: StencilFaceState;
+  readonly back: StencilFaceState;
+}
+
+export interface BlendComponentState {
+  readonly operation: GPUBlendOperation;
+  readonly srcFactor: GPUBlendFactor;
+  readonly dstFactor: GPUBlendFactor;
+}
+
+export interface BlendState {
+  readonly color: BlendComponentState;
+  readonly alpha: BlendComponentState;
+  /** RGBA channel write mask (bitmask: R=1, G=2, B=4, A=8). */
+  readonly writeMask: number;
+}
+
+export interface PipelineState {
+  readonly rasterizer: RasterizerState;
+  readonly depth?: DepthState;
+  readonly stencil?: StencilState;
+  /**
+   * Per-color-attachment blend state, keyed by the attachment name
+   * from the `FramebufferSignature`. Missing entries default to
+   * "no blending, write all channels".
+   */
+  readonly blends?: HashMap<string, BlendState>;
+  /** Multi-sample alpha-to-coverage. Default `false`. */
+  readonly alphaToCoverage?: boolean;
+}

package/src/core/renderContext.ts

@@ -0,0 +1,48 @@
+// RenderContext — ambient state available to AdaptiveResources
+// during evaluation. The runtime sets `encoder` before walking a
+// task's resources so that `compute(token)` calls inside an
+// AdaptiveResource can encode commands (uploads, compute passes,
+// render-to-texture) onto the current frame's encoder.
+//
+// Outside a frame (`encoder === null`) AdaptiveResources should
+// either return their cached handle or throw — they cannot do
+// GPU work without an encoder.
+
+interface RenderContextSlot {
+  encoder: GPUCommandEncoder | null;
+  withEncoder<R>(encoder: GPUCommandEncoder, fn: () => R): R;
+  requireEncoder(): GPUCommandEncoder;
+}
+
+export const RenderContext: RenderContextSlot = {
+  encoder: null,
+
+  /**
+   * Run `fn` with `encoder` exposed as the current frame encoder.
+   * Restores the previous value on exit. Nestable.
+   */
+  withEncoder<R>(encoder: GPUCommandEncoder, fn: () => R): R {
+    const prev = RenderContext.encoder;
+    RenderContext.encoder = encoder;
+    try {
+      return fn();
+    } finally {
+      RenderContext.encoder = prev;
+    }
+  },
+
+  /**
+   * Convenience: throws if no encoder is active. Use inside
+   * `compute(token)` of an AdaptiveResource that genuinely needs
+   * to encode work.
+   */
+  requireEncoder(): GPUCommandEncoder {
+    if (RenderContext.encoder === null) {
+      throw new Error(
+        "RenderContext: no active encoder. AdaptiveResource.compute() " +
+        "was called outside RenderContext.withEncoder(...).",
+      );
+    }
+    return RenderContext.encoder;
+  },
+};

package/src/core/renderObject.ts

@@ -0,0 +1,57 @@
+// RenderObject — the user-facing primitive: an effect + a bag of
+// named inputs + a draw call. Names are matched against the
+// shader's ProgramInterface during preparation; extras are
+// silently ignored, missing required bindings are an error.
+//
+// Every input is `aval<T>` over a *source* type (IBuffer, ITexture,
+// ISampler, …). The runtime (resources package) wraps these into
+// internal AdaptiveResources for upload + ref-counting; the user
+// never instantiates an AdaptiveResource directly.
+
+import type { HashMap, aval } from "@aardworx/wombat.adaptive";
+import type { IBuffer } from "./buffer.js";
+import type { BufferView } from "./bufferView.js";
+import type { DrawCall } from "./drawCall.js";
+import type { ISampler } from "./sampler.js";
+import type { ITexture } from "./texture.js";
+import type { PipelineState } from "./pipelineState.js";
+import type { Effect } from "./shader.js";
+
+export interface RenderObject {
+  /**
+   * A wombat.shader `Effect` — produced by the `vertex(...) /
+   * fragment(...) / effect(...)` markers (transformed at build
+   * time by `@aardworx/wombat.shader-vite`) or hand-built via
+   * `stage(module, ...)`. The runtime calls
+   * `effect.compile({ target: "wgsl" })` (Effect's own
+   * hole-value-keyed cache makes this free per frame).
+   *
+   * `Effect.id` (stable build-time hash) feeds the pipeline cache
+   * key, which means renaming a captured value invalidates only
+   * its specialization; everything else stays cached.
+   *
+   * For users with a precompiled `CompiledEffect` (e.g. from
+   * `compileShaderSource(...)`), wrap it with the test helper
+   * `fakeEffectFromCompiled` or call `stage(module)` to produce
+   * a real Effect.
+   */
+  readonly effect: Effect;
+  readonly pipelineState: PipelineState;
+
+  /** name → vertex buffer view; e.g. "position", "normal", "uv". */
+  readonly vertexAttributes: HashMap<string, aval<BufferView>>;
+  /** name → instance buffer view; e.g. "modelMatrix", "instanceColor". */
+  readonly instanceAttributes?: HashMap<string, aval<BufferView>>;
+  /** name → uniform value; runtime packs into UBO based on shader layout. */
+  readonly uniforms: HashMap<string, aval<unknown>>;
+  /** name → texture source (CPU image or pre-built GPUTexture). */
+  readonly textures: HashMap<string, aval<ITexture>>;
+  /** name → sampler source (descriptor or pre-built GPUSampler). */
+  readonly samplers: HashMap<string, aval<ISampler>>;
+  /** name → storage buffer source. */
+  readonly storageBuffers?: HashMap<string, aval<IBuffer>>;
+
+  /** Index buffer for indexed draws. */
+  readonly indices?: aval<BufferView>;
+  readonly drawCall: aval<DrawCall>;
+}

package/src/core/renderTask.ts

@@ -0,0 +1,17 @@
+// RenderTask — the compiled, runnable form of an alist<Command>.
+// The runtime returns one of these from `compile`; the user calls
+// `run(token)` to encode + submit a frame.
+
+import type { AdaptiveToken } from "@aardworx/wombat.adaptive";
+
+export interface IRenderTask {
+  /**
+   * Encode all commands into the GPU queue using the current
+   * adaptive state read via `token`. Returns once submission has
+   * been queued (does not wait for GPU completion).
+   */
+  run(token: AdaptiveToken): void;
+
+  /** Tear down resources owned by the task. Idempotent. */
+  dispose(): void;
+}

package/src/core/renderTree.ts

@@ -0,0 +1,29 @@
+// RenderTree — intra-pass ordering structure for RenderObjects.
+//
+// `Ordered` children execute left-to-right; `Unordered` children
+// can be reordered by the backend to minimise pipeline / bind-
+// group / vertex-buffer state changes. The Adaptive variants
+// fold reactive containers (alist, aset, aval) directly into the
+// tree.
+
+import type { aval, alist, aset } from "@aardworx/wombat.adaptive";
+import type { RenderObject } from "./renderObject.js";
+
+export type RenderTree =
+  | { readonly kind: "Empty" }
+  | { readonly kind: "Leaf"; readonly object: RenderObject }
+  | { readonly kind: "Ordered"; readonly children: readonly RenderTree[] }
+  | { readonly kind: "Unordered"; readonly children: readonly RenderTree[] }
+  | { readonly kind: "Adaptive"; readonly tree: aval<RenderTree> }
+  | { readonly kind: "OrderedFromList"; readonly children: alist<RenderTree> }
+  | { readonly kind: "UnorderedFromSet"; readonly children: aset<RenderTree> };
+
+export const RenderTree = {
+  empty: { kind: "Empty" } as const satisfies RenderTree,
+  leaf: (object: RenderObject): RenderTree => ({ kind: "Leaf", object }),
+  ordered: (...children: RenderTree[]): RenderTree => ({ kind: "Ordered", children }),
+  unordered: (...children: RenderTree[]): RenderTree => ({ kind: "Unordered", children }),
+  adaptive: (tree: aval<RenderTree>): RenderTree => ({ kind: "Adaptive", tree }),
+  orderedFromList: (children: alist<RenderTree>): RenderTree => ({ kind: "OrderedFromList", children }),
+  unorderedFromSet: (children: aset<RenderTree>): RenderTree => ({ kind: "UnorderedFromSet", children }),
+} as const;

package/src/core/sampler.ts

@@ -0,0 +1,12 @@
+// ISampler — sampler source. Either a pre-built `GPUSampler` or a
+// descriptor for the runtime to materialise (samplers are cheap
+// and dedupable, so descriptors are the common path).
+
+export type ISampler =
+  | { readonly kind: "gpu"; readonly sampler: GPUSampler }
+  | { readonly kind: "desc"; readonly descriptor: GPUSamplerDescriptor };
+
+export const ISampler = {
+  fromGPU(sampler: GPUSampler): ISampler { return { kind: "gpu", sampler }; },
+  fromDescriptor(descriptor: GPUSamplerDescriptor): ISampler { return { kind: "desc", descriptor }; },
+} as const;

package/src/core/shader.ts

@@ -0,0 +1,28 @@
+// Re-exports of the wombat.shader runtime types consumed by the
+// rendering layer. We do NOT duplicate or re-shape these — the
+// rendering layer is just a consumer of wombat.shader's
+// `Effect` / `CompiledEffect` / `ProgramInterface`.
+
+export type {
+  Effect,
+  ComputeShader,
+  Stage,
+  HoleGetter,
+  HoleGetters,
+  CompiledEffect,
+  CompiledStage,
+  Target,
+} from "@aardworx/wombat.shader";
+
+export type {
+  ProgramInterface,
+  StageInfo,
+  AttributeInfo,
+  OutputInfo,
+  LooseUniformInfo,
+  UniformBlockInfo,
+  UniformFieldInfo,
+  SamplerInfo,
+  TextureInfo,
+  StorageBufferInfo,
+} from "@aardworx/wombat.shader";

package/src/core/texture.ts

@@ -0,0 +1,63 @@
+// ITexture — texture source that can be either a real GPU texture
+// or a host-side image. Mirrors the IBuffer pattern.
+//
+// Host sources cover everything WebGPU's `copyExternalImageToTexture`
+// or `writeTexture` can accept:
+//   - `ImageBitmap`, `HTMLImageElement`, `HTMLVideoElement`,
+//     `HTMLCanvasElement`, `OffscreenCanvas`, `ImageData` —
+//     uploaded via `copyExternalImageToTexture`.
+//   - Raw `{ data, width, height, format }` — uploaded via
+//     `queue.writeTexture` (one mip; runtime can synthesise the
+//     rest if requested).
+
+export interface RawTextureSource {
+  readonly kind: "raw";
+  readonly data: ArrayBuffer | ArrayBufferView;
+  readonly width: number;
+  readonly height: number;
+  readonly depthOrArrayLayers?: number;
+  readonly format: GPUTextureFormat;
+  readonly mipLevelCount?: number;
+}
+
+export interface ExternalTextureSource {
+  readonly kind: "external";
+  readonly source:
+    | ImageBitmap
+    | HTMLImageElement
+    | HTMLVideoElement
+    | HTMLCanvasElement
+    | OffscreenCanvas
+    | ImageData;
+  /** Override the format the runtime should allocate (default: "rgba8unorm"). */
+  readonly format?: GPUTextureFormat;
+  /** Generate a mip chain on upload. Default `false`. */
+  readonly generateMips?: boolean;
+}
+
+export type HostTextureSource = RawTextureSource | ExternalTextureSource;
+
+export type ITexture =
+  | { readonly kind: "gpu"; readonly texture: GPUTexture }
+  | { readonly kind: "host"; readonly source: HostTextureSource };
+
+export const ITexture = {
+  fromGPU(texture: GPUTexture): ITexture {
+    return { kind: "gpu", texture };
+  },
+  fromExternal(
+    source: ExternalTextureSource["source"],
+    opts: { format?: GPUTextureFormat; generateMips?: boolean } = {},
+  ): ITexture {
+    const ext: ExternalTextureSource = {
+      kind: "external",
+      source,
+      ...(opts.format !== undefined ? { format: opts.format } : {}),
+      ...(opts.generateMips !== undefined ? { generateMips: opts.generateMips } : {}),
+    };
+    return { kind: "host", source: ext };
+  },
+  fromRaw(raw: Omit<RawTextureSource, "kind">): ITexture {
+    return { kind: "host", source: { kind: "raw", ...raw } };
+  },
+} as const;

package/src/index.ts

@@ -0,0 +1,18 @@
+// Public API of `@aardworx/wombat.rendering`.
+//
+// Default entry re-exports everything: types, resource preparers,
+// command-stream functions, runtime, and the window/canvas glue.
+// Subpath exports give granular access for advanced consumers.
+//
+//   import { ... } from "@aardworx/wombat.rendering";        // everything
+//   import { ... } from "@aardworx/wombat.rendering/core";   // types only
+//   import { ... } from "@aardworx/wombat.rendering/resources";
+//   import { ... } from "@aardworx/wombat.rendering/commands";
+//   import { ... } from "@aardworx/wombat.rendering/runtime";
+//   import { ... } from "@aardworx/wombat.rendering/window";
+
+export * from "./core/index.js";
+export * from "./resources/index.js";
+export * from "./commands/index.js";
+export * from "./runtime/index.js";
+export * from "./window/index.js";

package/src/resources/adaptiveBuffer.ts

@@ -0,0 +1,135 @@
+// prepareAdaptiveBuffer — lift `aval<IBuffer>` to
+// `AdaptiveResource<GPUBuffer>`.
+//
+// Behaviour:
+//   - On `acquire` (refCount 0→1): subscribes, allocates nothing yet.
+//   - On `compute(token)`:
+//     - reads the source `aval<IBuffer>`;
+//     - if it's `gpu`: returns the user's handle directly. We
+//       don't own it; `destroy()` will not free it.
+//     - if it's `host`: ensures we own a `GPUBuffer` of sufficient
+//       size + correct usage flags, encodes a `writeBuffer` (via
+//       device.queue) to upload the bytes, returns the owned
+//       buffer. Reuses the existing buffer when capacity allows;
+//       reallocates on growth.
+//   - On `destroy`: frees the owned buffer (if any).
+//
+// `writeBuffer` does not require a GPUCommandEncoder — it goes via
+// `GPUQueue.writeBuffer`, scheduled at the next submit. That keeps
+// the upload path simple and avoids needing `RenderContext.encoder`
+// for plain CPU→GPU buffer flow. (Compute-produced buffers will
+// need the encoder; that's a different code path.)
+
+import {
+  AdaptiveResource,
+  tryAcquire,
+  tryRelease,
+  type IBuffer,
+} from "../core/index.js";
+import {
+  type AdaptiveToken,
+  type aval,
+} from "@aardworx/wombat.adaptive";
+import { BufferUsage } from "./webgpuFlags.js";
+
+export interface PrepareAdaptiveBufferOptions {
+  /** Bitwise OR of GPUBufferUsage flags. `COPY_DST` is added automatically when needed. */
+  readonly usage: GPUBufferUsageFlags;
+  /** Optional debug label forwarded to created GPUBuffers. */
+  readonly label?: string;
+  /**
+   * Reuse the existing GPUBuffer when the new host data fits in
+   * the current allocation. Default `true`. Set `false` to force
+   * a fresh buffer on every host-side change (rarely useful).
+   */
+  readonly reuseOnFit?: boolean;
+}
+
+class AdaptiveBuffer extends AdaptiveResource<GPUBuffer> {
+  private _owned: GPUBuffer | undefined = undefined;
+  private _ownedCapacity = 0;
+
+  constructor(
+    private readonly device: GPUDevice,
+    private readonly source: aval<IBuffer>,
+    private readonly opts: PrepareAdaptiveBufferOptions,
+  ) {
+    super();
+  }
+
+  protected create(): void {
+    tryAcquire(this.source);
+  }
+
+  protected destroy(): void {
+    if (this._owned !== undefined) {
+      this._owned.destroy();
+      this._owned = undefined;
+      this._ownedCapacity = 0;
+    }
+    tryRelease(this.source);
+  }
+
+  override compute(token: AdaptiveToken): GPUBuffer {
+    const src = this.source.getValue(token);
+    if (src.kind === "gpu") {
+      // Caller-owned buffer; drop any owned allocation we still hold.
+      if (this._owned !== undefined) {
+        this._owned.destroy();
+        this._owned = undefined;
+        this._ownedCapacity = 0;
+      }
+      return src.buffer;
+    }
+    // host — upload via queue.writeBuffer.
+    const usage = this.opts.usage | BufferUsage.COPY_DST;
+    const reuseOnFit = this.opts.reuseOnFit ?? true;
+    const requiredSize = roundUp4(src.sizeBytes);
+    if (
+      this._owned === undefined
+      || !reuseOnFit
+      || requiredSize > this._ownedCapacity
+    ) {
+      if (this._owned !== undefined) this._owned.destroy();
+      const desc: GPUBufferDescriptor = {
+        size: requiredSize,
+        usage,
+        ...(this.opts.label !== undefined ? { label: this.opts.label } : {}),
+      };
+      this._owned = this.device.createBuffer(desc);
+      this._ownedCapacity = requiredSize;
+    }
+    // writeBuffer accepts ArrayBuffer or any ArrayBufferView.
+    const data = src.data;
+    if (data instanceof ArrayBuffer) {
+      this.device.queue.writeBuffer(this._owned, 0, data, 0, src.sizeBytes);
+    } else {
+      this.device.queue.writeBuffer(
+        this._owned,
+        0,
+        data.buffer,
+        data.byteOffset,
+        src.sizeBytes,
+      );
+    }
+    return this._owned;
+  }
+}
+
+function roundUp4(n: number): number {
+  return (n + 3) & ~3;
+}
+
+/**
+ * Wrap an `aval<IBuffer>` as a ref-counted, adaptively-uploaded
+ * `AdaptiveResource<GPUBuffer>`. The resource is itself an
+ * `aval<GPUBuffer>` — downstream consumers can `getValue(token)`
+ * inside their own adaptive evaluation.
+ */
+export function prepareAdaptiveBuffer(
+  device: GPUDevice,
+  source: aval<IBuffer>,
+  opts: PrepareAdaptiveBufferOptions,
+): AdaptiveResource<GPUBuffer> {
+  return new AdaptiveBuffer(device, source, opts);
+}

package/src/resources/adaptiveSampler.ts

@@ -0,0 +1,82 @@
+// prepareAdaptiveSampler — lift `aval<ISampler>` to
+// `AdaptiveResource<GPUSampler>`.
+//
+// Samplers are cheap and structurally-identifiable — the device
+// dedupes them via a descriptor cache. Per AdaptiveResource we
+// just track the most recent handle; on descriptor change we
+// fetch a fresh one from the cache.
+
+import {
+  AdaptiveResource,
+  tryAcquire,
+  tryRelease,
+  type ISampler,
+} from "../core/index.js";
+import {
+  type AdaptiveToken,
+  type aval,
+} from "@aardworx/wombat.adaptive";
+
+class SamplerCache {
+  private readonly map = new Map<string, GPUSampler>();
+  constructor(private readonly device: GPUDevice) {}
+  get(desc: GPUSamplerDescriptor): GPUSampler {
+    const k = key(desc);
+    let s = this.map.get(k);
+    if (s === undefined) {
+      s = this.device.createSampler(desc);
+      this.map.set(k, s);
+    }
+    return s;
+  }
+}
+
+function key(d: GPUSamplerDescriptor): string {
+  return [
+    d.addressModeU ?? "clamp-to-edge",
+    d.addressModeV ?? "clamp-to-edge",
+    d.addressModeW ?? "clamp-to-edge",
+    d.magFilter ?? "nearest",
+    d.minFilter ?? "nearest",
+    d.mipmapFilter ?? "nearest",
+    d.lodMinClamp ?? 0,
+    d.lodMaxClamp ?? 32,
+    d.compare ?? "",
+    d.maxAnisotropy ?? 1,
+  ].join("|");
+}
+
+const caches = new WeakMap<GPUDevice, SamplerCache>();
+function cacheFor(device: GPUDevice): SamplerCache {
+  let c = caches.get(device);
+  if (c === undefined) {
+    c = new SamplerCache(device);
+    caches.set(device, c);
+  }
+  return c;
+}
+
+class AdaptiveSampler extends AdaptiveResource<GPUSampler> {
+  constructor(
+    private readonly device: GPUDevice,
+    private readonly source: aval<ISampler>,
+  ) { super(); }
+  protected create(): void { tryAcquire(this.source); }
+  protected destroy(): void {
+    // We never own the GPUSampler — the cache does. Just propagate
+    // release to the source aval (in case it's an AdaptiveResource).
+    tryRelease(this.source);
+  }
+  override compute(token: AdaptiveToken): GPUSampler {
+    const s = this.source.getValue(token);
+    if (s.kind === "gpu") return s.sampler;
+    return cacheFor(this.device).get(s.descriptor);
+  }
+}
+
+export function prepareAdaptiveSampler(
+  device: GPUDevice,
+  source: aval<ISampler>,
+): AdaptiveResource<GPUSampler> {
+  return new AdaptiveSampler(device, source);
+}