@aardworx/wombat.rendering 0.6.0 → 0.7.0

package/src/core/elementType.ts

@@ -0,0 +1,84 @@
+// ElementType — the data type of a single element in a BufferView.
+//
+// Mirrors Aardvark.Rendering's `BufferView.ElementType : System.Type`
+// pattern: structural information about the element kept separate
+// from the per-frame buffer content. The runtime maps `ElementType`
+// to a `GPUVertexFormat`/`GPUIndexFormat` and a byte size at
+// pipeline-layout time.
+
+export type ElementType =
+  // scalar
+  | "f32" | "u32" | "i32"
+  | "u16" | "i16"
+  | "u8"  | "i8"
+  // vec — float
+  | "v2f" | "v3f" | "v4f"
+  // vec — int
+  | "v2i" | "v3i" | "v4i"
+  // vec — uint
+  | "v2u" | "v3u" | "v4u"
+  // matrix (float, square)
+  | "m22f" | "m33f" | "m44f"
+  // packed colour
+  | "c4b" | "c3b";
+
+export const ElementType = {
+  /** Size of one element in bytes. */
+  byteSize(t: ElementType): number {
+    switch (t) {
+      case "f32": case "u32": case "i32": return 4;
+      case "u16": case "i16": return 2;
+      case "u8":  case "i8":  return 1;
+      case "v2f": case "v2i": case "v2u": return 8;
+      case "v3f": case "v3i": case "v3u": return 12;
+      case "v4f": case "v4i": case "v4u": return 16;
+      case "m22f": return 16;
+      case "m33f": return 36;
+      case "m44f": return 64;
+      case "c4b": return 4;
+      case "c3b": return 3;
+    }
+  },
+
+  /**
+   * GPUVertexFormat for use as a vertex / instance attribute.
+   * `normalized=true` only affects integer types — picks the `unorm`
+   * / `snorm` form. Matrix types are not directly supported as
+   * vertex formats; the auto-instancing pass splits them into
+   * column attributes upstream.
+   */
+  toVertexFormat(t: ElementType, normalized = false): GPUVertexFormat {
+    switch (t) {
+      case "f32": return "float32";
+      case "u32": return "uint32";
+      case "i32": return "sint32";
+      case "v2f": return "float32x2";
+      case "v3f": return "float32x3";
+      case "v4f": return "float32x4";
+      case "v2i": return "sint32x2";
+      case "v3i": return "sint32x3";
+      case "v4i": return "sint32x4";
+      case "v2u": return "uint32x2";
+      case "v3u": return "uint32x3";
+      case "v4u": return "uint32x4";
+      case "u16": return normalized ? "unorm16x2" as GPUVertexFormat : "uint16";
+      case "i16": return normalized ? "snorm16x2" as GPUVertexFormat : "sint16";
+      case "u8":  return normalized ? "unorm8x4"  as GPUVertexFormat : "uint8";
+      case "i8":  return normalized ? "snorm8x4"  as GPUVertexFormat : "sint8";
+      case "c4b": return normalized ? "unorm8x4" : "uint8x4";
+      case "c3b":
+        // No 3-component byte format in WebGPU; promoted to x4 with
+        // a dummy fourth byte by the upload path.
+        throw new Error(`ElementType.toVertexFormat: c3b cannot be a vertex format directly; pad to c4b`);
+      case "m22f": case "m33f": case "m44f":
+        throw new Error(`ElementType.toVertexFormat: ${t} is a matrix; split into column attributes first`);
+    }
+  },
+
+  /** Index format. Throws unless the type is `u16` or `u32`. */
+  toIndexFormat(t: ElementType): GPUIndexFormat {
+    if (t === "u16") return "uint16";
+    if (t === "u32") return "uint32";
+    throw new Error(`ElementType.toIndexFormat: ${t} is not a valid index type (use u16 or u32)`);
+  },
+} as const;

package/src/core/index.ts

@@ -11,10 +11,14 @@ export type {
   HostBufferSource,
 } from "./buffer.js";
 
-export type {
+export {
   BufferView,
 } from "./bufferView.js";
 
+export {
+  ElementType,
+} from "./elementType.js";
+
 export type {
   ClearColor,
   ClearValues,

package/src/core/renderObject.ts

@@ -45,9 +45,9 @@ export interface RenderObject {
    * individual buffer values are reactive. The shader's required-input
    * set is fixed at compile; the map must contain at least those names.
    */
-  readonly vertexAttributes: HashMap<string, aval<BufferView>>;
+  readonly vertexAttributes: HashMap<string, BufferView>;
   /** name → instance buffer view; e.g. "modelMatrix", "instanceColor". */
-  readonly instanceAttributes?: HashMap<string, aval<BufferView>>;
+  readonly instanceAttributes?: HashMap<string, 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). */
@@ -58,6 +58,6 @@ export interface RenderObject {
   readonly storageBuffers?: HashMap<string, aval<IBuffer>>;
 
   /** Index buffer for indexed draws. */
-  readonly indices?: aval<BufferView>;
+  readonly indices?: BufferView;
   readonly drawCall: aval<DrawCall>;
 }

package/src/resources/preparedRenderObject.ts

@@ -14,6 +14,8 @@
 
 import {
   AdaptiveResource,
+  BufferView,
+  ElementType,
   type CompiledEffect,
   type FramebufferSignature,
   type ProgramInterface,
@@ -25,7 +27,6 @@ import {
   HashMap,
   cval,
 } from "@aardworx/wombat.adaptive";
-import type { BufferView } from "../core/bufferView.js";
 import type { Type } from "@aardworx/wombat.shader/ir";
 import { prepareAdaptiveBuffer } from "./adaptiveBuffer.js";
 import { prepareAdaptiveTexture } from "./adaptiveTexture.js";
@@ -34,32 +35,6 @@ import { prepareUniformBuffer } from "./uniformBuffer.js";
 import { compileRenderPipeline, type CompileRenderPipelineDescription } from "./renderPipeline.js";
 import { BufferUsage, ShaderStage } from "./webgpuFlags.js";
 
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function isIndexFormat(fmt: string): boolean {
-  return fmt === "uint16" || fmt === "uint32";
-}
-
-function vertexFormatStride(fmt: GPUVertexFormat): number {
-  switch (fmt) {
-    case "float32": return 4;
-    case "float32x2": return 8;
-    case "float32x3": return 12;
-    case "float32x4": return 16;
-    case "uint32": case "sint32": return 4;
-    case "uint32x2": case "sint32x2": return 8;
-    case "uint32x3": case "sint32x3": return 12;
-    case "uint32x4": case "sint32x4": return 16;
-    case "uint16x2": case "sint16x2": case "float16x2": return 4;
-    case "uint16x4": case "sint16x4": case "float16x4": return 8;
-    case "uint8x2": case "sint8x2": case "unorm8x2": case "snorm8x2": return 2;
-    case "uint8x4": case "sint8x4": case "unorm8x4": case "snorm8x4": return 4;
-    default: throw new Error(`vertexFormatStride: unsupported format ${fmt}`);
-  }
-}
-
 interface VertexBindingInfo {
   readonly name: string;
   readonly slot: number;
@@ -371,10 +346,10 @@ export class PreparedRenderObject {
     private readonly device: GPUDevice,
     private readonly vertexBindings: readonly VertexBindingInfo[],
     private readonly vertexBuffers: ReadonlyMap<string, AdaptiveResource<GPUBuffer>>,
-    private readonly vertexViews: ReadonlyMap<string, aval<import("../core/index.js").BufferView>>,
+    private readonly vertexViews: ReadonlyMap<string, BufferView>,
     private readonly indexBuffer: AdaptiveResource<GPUBuffer> | undefined,
     private readonly indexFormat: GPUIndexFormat | undefined,
-    private readonly indices: aval<import("../core/index.js").BufferView> | undefined,
+    private readonly indices: BufferView | undefined,
     groups: readonly GroupDesc[],
     private readonly drawCall: aval<import("../core/index.js").DrawCall>,
     pipelineCtx: PipelineBuildContext,
@@ -479,15 +454,12 @@ export class PreparedRenderObject {
     for (const vb of this.vertexBindings) {
       const res = this.vertexBuffers.get(vb.name);
       if (res === undefined) throw new Error(`PreparedRenderObject.record: missing vertex buffer for "${vb.name}"`);
-      const viewAval = this.vertexViews.get(vb.name);
-      const view = viewAval !== undefined ? viewAval.getValue(token) : undefined;
+      const view = this.vertexViews.get(vb.name);
       const buf = res.getValue(token);
-      if (view !== undefined && view.offset > 0) {
-        // size omitted → WebGPU uses (buffer.size − offset). The
-        // BufferView's count·stride span doesn't include the offset,
-        // so passing it here would request bytes past the end of the
-        // buffer for any non-zero offset; let WebGPU default.
-        pass.setVertexBuffer(vb.slot, buf, view.offset);
+      const offset = view !== undefined ? BufferView.offsetOf(view) : 0;
+      if (offset > 0) {
+        // size omitted → WebGPU uses (buffer.size − offset).
+        pass.setVertexBuffer(vb.slot, buf, offset);
       } else {
         pass.setVertexBuffer(vb.slot, buf);
       }
@@ -495,8 +467,8 @@ export class PreparedRenderObject {
 
     if (this.indexBuffer !== undefined && this.indices !== undefined && this.indexFormat !== undefined) {
       const buf = this.indexBuffer.getValue(token);
-      const view = this.indices.getValue(token);
-      pass.setIndexBuffer(buf, this.indexFormat, view.offset, view.count * (this.indexFormat === "uint16" ? 2 : 4));
+      // size omitted → WebGPU uses (buffer.size − offset).
+      pass.setIndexBuffer(buf, this.indexFormat, BufferView.offsetOf(this.indices));
     }
 
     const dc = this.drawCall.getValue(token);
@@ -541,12 +513,16 @@ export function prepareRenderObject(
 
   // Per-attribute resolution + grouping. Multiple attributes can
   // share one underlying GPUBuffer slot when they all point at the
-  // same `IBuffer` with the same stride + stepMode (the
-  // auto-instancing rewrite emits 4 vec4 column attributes per
-  // M44 instance trafo — without packing we'd hit
-  // `maxVertexBuffers` (8) for any moderately rich instancing
-  // scope). Each attribute's `view.offset` becomes its
+  // same `aval<IBuffer>` (by reference identity) with the same
+  // stride + stepMode (the auto-instancing rewrite emits 4 vec4
+  // column attributes per M44 instance trafo — without packing
+  // we'd hit `maxVertexBuffers` (8) for any moderately rich
+  // instancing scope). Each attribute's `view.offset` becomes its
   // shader-location offset within the shared layout.
+  //
+  // BufferView is now structural-eager (elementType/offset/stride),
+  // so no `force()` is needed to discover layout — the attribute
+  // grouping reads the plain fields directly.
   interface ResolvedBinding {
     readonly name: string;
     readonly shaderLocation: number;
@@ -554,8 +530,7 @@ export function prepareRenderObject(
     readonly stride: number;
     readonly offset: number;
     readonly format: GPUVertexFormat;
-    readonly viewAval: aval<import("../core/index.js").BufferView>;
-    readonly buffer: import("../core/index.js").IBuffer;
+    readonly view: BufferView;
   }
   const resolved: ResolvedBinding[] = [];
   for (const vb of vertexBindings) {
@@ -567,33 +542,28 @@ export function prepareRenderObject(
     const isInstance = fromVertex === undefined && fromInstance !== undefined;
     const stepMode: GPUVertexStepMode = isInstance ? "instance" : "vertex";
 
-    const viewAval = (fromVertex ?? fromInstance)!;
-    const initialView = viewAval.force();
-    const viewFormat = initialView.format as GPUVertexFormat | undefined;
-    const format = (viewFormat !== undefined && !isIndexFormat(viewFormat))
-      ? viewFormat : vb.format;
-    const stride = initialView.stride === 0
-      ? 0
-      : (initialView.stride > 0 ? initialView.stride : vertexFormatStride(format));
+    const view = (fromVertex ?? fromInstance)!;
+    const format = ElementType.toVertexFormat(view.elementType, view.normalized ?? false);
+    const stride = BufferView.strideOf(view);
+    const offset = BufferView.offsetOf(view);
     resolved.push({
       name: vb.name,
       shaderLocation: vb.slot,
-      stepMode, stride, offset: initialView.offset,
-      format, viewAval, buffer: initialView.buffer,
+      stepMode, stride, offset,
+      format, view,
     });
   }
 
-  // Group resolved bindings by (IBuffer, stride, stepMode). Each
-  // group becomes one GPUVertexBufferLayout with one or more
-  // attributes; multiple bindings sharing one buffer collapse to a
-  // single setVertexBuffer call at draw time.
+  // Group resolved bindings by (IBuffer-aval identity, stride, stepMode).
+  // The aval reference is the natural identity now that BufferView
+  // owns its `aval<IBuffer>` directly.
   type GroupKey = string;
   interface BindingGroup {
     readonly key: GroupKey;
     readonly slot: number;             // GPU vertex-buffer slot index
     readonly stride: number;
     readonly stepMode: GPUVertexStepMode;
-    readonly viewAval: aval<import("../core/index.js").BufferView>;
+    readonly view: BufferView;
     readonly bufferRes: AdaptiveResource<GPUBuffer>;
     readonly members: ResolvedBinding[];
   }
@@ -607,26 +577,25 @@ export function prepareRenderObject(
   const vbGroups = new Map<GroupKey, BindingGroup>();
   let nextSlot = 0;
   const vertexBuffers = new Map<string, AdaptiveResource<GPUBuffer>>();
-  const vertexViews = new Map<string, aval<import("../core/index.js").BufferView>>();
+  const vertexViews = new Map<string, BufferView>();
   for (const r of resolved) {
-    const bufId = idOf(r.buffer as unknown as object);
+    const bufId = idOf(r.view.buffer as unknown as object);
     const key = `${bufId}|${r.stride}|${r.stepMode}`;
     let group = vbGroups.get(key);
     if (!group) {
-      const bufAval = r.viewAval.map(view => view.buffer);
-      const bufferRes = prepareAdaptiveBuffer(device, bufAval, {
+      const bufferRes = prepareAdaptiveBuffer(device, r.view.buffer, {
         usage: BufferUsage.VERTEX,
         ...(opts.label !== undefined ? { label: `${opts.label}.${r.name}` } : {}),
       });
       group = {
         key, slot: nextSlot++, stride: r.stride, stepMode: r.stepMode,
-        viewAval: r.viewAval, bufferRes, members: [],
+        view: r.view, bufferRes, members: [],
       };
       vbGroups.set(key, group);
     }
     group.members.push(r);
     vertexBuffers.set(r.name, group.bufferRes);
-    vertexViews.set(r.name, r.viewAval);
+    vertexViews.set(r.name, r.view);
   }
   const vertexLayouts: GPUVertexBufferLayout[] = [];
   for (const g of vbGroups.values()) {
@@ -663,21 +632,16 @@ export function prepareRenderObject(
   }
   vertexBindings = drawTimeBindings;
 
-  // Index buffer — `indexFormat` from BufferView wins; defaults to uint32.
+  // Index buffer — `elementType` (u16 / u32) determines `GPUIndexFormat`.
+  // Structural fields are eager on BufferView, so no force needed.
   let indexBuffer: AdaptiveResource<GPUBuffer> | undefined;
   let indexFormat: GPUIndexFormat | undefined;
   if (obj.indices !== undefined) {
-    const bufAval = obj.indices.map(v => v.buffer);
-    indexBuffer = prepareAdaptiveBuffer(device, bufAval, {
+    indexBuffer = prepareAdaptiveBuffer(device, obj.indices.buffer, {
       usage: BufferUsage.INDEX,
       ...(opts.label !== undefined ? { label: `${opts.label}.indices` } : {}),
     });
-    // Construction-time read to discover the index format. The
-    // BufferView aval is expected to settle on a stable format —
-    // changing index format would require a fresh PreparedRO.
-    const initial = obj.indices.force();
-    indexFormat = initial.indexFormat
-      ?? (initial.format === "uint16" ? "uint16" : "uint32");
+    indexFormat = ElementType.toIndexFormat(obj.indices.elementType);
   }
 
   const slotOf = (e: { group: number; slot: number }) => e.slot;
@@ -767,8 +731,8 @@ export function prepareRenderObject(
   );
 }
 
-function emptyAttrMap(): HashMap<string, aval<BufferView>> {
-  return HashMap.empty<string, aval<BufferView>>();
+function emptyAttrMap(): HashMap<string, BufferView> {
+  return HashMap.empty<string, BufferView>();
 }
 
 /**