@aardworx/wombat.rendering 0.6.0 → 0.7.1

package/src/core/elementType.ts

@@ -0,0 +1,178 @@
+// ElementType — runtime token + structural metadata for the data
+// type of a single element in a `BufferView`. The TypeScript-side
+// equivalent of F#'s `typeof<T>` / `System.Type`: a value (not a
+// string tag) carrying byte size, vertex / index format, and a
+// phantom type parameter that flows through to `BufferView<T>`-
+// generic call sites.
+//
+// All entries are exposed as singleton properties on `ElementType`:
+//
+//   ElementType.V3f         // ElementKind<V3f>
+//   ElementType.U16         // ElementKind<number>
+//   ElementType.M44f        // ElementKind<M44f>
+//
+// `BufferView.ofArray` infers the kind from the source array's
+// constructor identity (V3fArray → ElementType.V3f, Float32Array →
+// ElementType.F32, etc.) so the explicit second argument is rarely
+// needed.
+
+import type {
+  V2f, V3f, V4f, M22f, M33f, M44f, V2i, V3i, V4i,
+} from "@aardworx/wombat.base";
+import {
+  V2fArray, V3fArray, V4fArray,
+  V2iArray, V3iArray, V4iArray,
+  V2uiArray, V3uiArray, V4uiArray,
+} from "@aardworx/wombat.base";
+
+// ---------------------------------------------------------------------------
+// ElementKind<T>
+// ---------------------------------------------------------------------------
+
+/**
+ * Phantom-typed token describing a single element's data type. The
+ * `T` parameter is a brand only — it carries the source-side type
+ * (V3f, M44f, number, …) into the type system at zero runtime cost.
+ *
+ * Identity equality is the equality used everywhere in the renderer
+ * (group keys, bind plans). All instances are singletons under the
+ * `ElementType` namespace below.
+ */
+export class ElementKind<T> {
+  constructor(
+    /** Short human-readable tag (e.g. `"v3f"`, `"u16"`). */
+    readonly name: string,
+    /** Size of one element in bytes. */
+    readonly byteSize: number,
+    /** GPUVertexFormat for use as a vertex attribute. `undefined` for matrix and non-vertex types. */
+    readonly vertexFormat: GPUVertexFormat | undefined,
+    /** GPUIndexFormat when used as an index buffer. `undefined` unless the type is `u16` / `u32`. */
+    readonly indexFormat: GPUIndexFormat | undefined,
+  ) {}
+
+  /** Phantom — never read at runtime. Forces TS to track T. */
+  declare readonly _brand: T;
+
+  toString(): string { return this.name; }
+}
+
+/**
+ * `ElementType` doubles as a type alias (the structural shape) and
+ * a value namespace (the singleton tokens). `ElementType` in type
+ * position is `ElementKind<unknown>`; in value position it's the
+ * collection of singletons below.
+ */
+export type ElementType = ElementKind<unknown>;
+
+// ---------------------------------------------------------------------------
+// Singleton tokens
+// ---------------------------------------------------------------------------
+
+const _V2f  = new ElementKind<V2f>("v2f",   8, "float32x2", undefined);
+const _V3f  = new ElementKind<V3f>("v3f",  12, "float32x3", undefined);
+const _V4f  = new ElementKind<V4f>("v4f",  16, "float32x4", undefined);
+const _M22f = new ElementKind<M22f>("m22f", 16, undefined, undefined);
+const _M33f = new ElementKind<M33f>("m33f", 36, undefined, undefined);
+const _M44f = new ElementKind<M44f>("m44f", 64, undefined, undefined);
+const _V2i  = new ElementKind<V2i>("v2i",   8, "sint32x2", undefined);
+const _V3i  = new ElementKind<V3i>("v3i",  12, "sint32x3", undefined);
+const _V4i  = new ElementKind<V4i>("v4i",  16, "sint32x4", undefined);
+const _V2u  = new ElementKind<V2i>("v2u",   8, "uint32x2", undefined);
+const _V3u  = new ElementKind<V3i>("v3u",  12, "uint32x3", undefined);
+const _V4u  = new ElementKind<V4i>("v4u",  16, "uint32x4", undefined);
+const _F32  = new ElementKind<number>("f32", 4, "float32", undefined);
+const _U32  = new ElementKind<number>("u32", 4, "uint32",  "uint32");
+const _I32  = new ElementKind<number>("i32", 4, "sint32",  undefined);
+const _U16  = new ElementKind<number>("u16", 2, undefined, "uint16");
+const _I16  = new ElementKind<number>("i16", 2, undefined, undefined);
+const _U8   = new ElementKind<number>("u8",  1, undefined, undefined);
+const _I8   = new ElementKind<number>("i8",  1, undefined, undefined);
+
+/**
+ * Construct a vertex view; throws if the kind has no vertex format
+ * (matrix / unsupported type).
+ */
+function asVertexFormat(t: ElementType): GPUVertexFormat {
+  if (t.vertexFormat === undefined) {
+    throw new Error(
+      `ElementType.${t.name}: no GPUVertexFormat (matrices must be split into column attributes; ` +
+      `unsupported types must be repacked first)`,
+    );
+  }
+  return t.vertexFormat;
+}
+
+function asIndexFormat(t: ElementType): GPUIndexFormat {
+  if (t.indexFormat === undefined) {
+    throw new Error(`ElementType.${t.name}: not a valid index type (use ElementType.U16 or ElementType.U32)`);
+  }
+  return t.indexFormat;
+}
+
+// ---------------------------------------------------------------------------
+// Constructor → ElementType registry — drives `BufferView.ofArray`
+// auto-inference. Keyed on class identity (V3fArray, Float32Array,
+// …) so it survives minification.
+// ---------------------------------------------------------------------------
+
+const FROM_CTOR: ReadonlyMap<unknown, ElementType> = new Map<unknown, ElementType>([
+  // wombat.base packed arrays
+  [V2fArray,  _V2f], [V3fArray, _V3f], [V4fArray, _V4f],
+  [V2iArray,  _V2i], [V3iArray, _V3i], [V4iArray, _V4i],
+  [V2uiArray, _V2u], [V3uiArray, _V3u], [V4uiArray, _V4u],
+  // native typed arrays (interpreted as scalars)
+  [Float32Array, _F32],
+  [Uint32Array,  _U32],
+  [Int32Array,   _I32],
+  [Uint16Array,  _U16],
+  [Int16Array,   _I16],
+  [Uint8Array,   _U8],
+  [Int8Array,    _I8],
+]);
+
+function fromArray(arr: unknown): ElementType {
+  const ctor = (arr as { constructor?: unknown }).constructor;
+  if (ctor === undefined) {
+    throw new Error("ElementType.fromArray: input has no constructor");
+  }
+  const et = FROM_CTOR.get(ctor);
+  if (et === undefined) {
+    const name = (ctor as { name?: string }).name ?? "<anonymous>";
+    throw new Error(
+      `ElementType.fromArray: cannot infer ElementType from ${name}; ` +
+      `pass the kind explicitly (e.g. ElementType.V3f)`,
+    );
+  }
+  return et;
+}
+
+// ---------------------------------------------------------------------------
+// Public namespace
+// ---------------------------------------------------------------------------
+
+/**
+ * Singleton tokens + helpers. Most call sites use the singleton
+ * directly (`ElementType.V3f`); the helpers are kept on the
+ * namespace so `import { ElementType }` is the only import you
+ * need.
+ */
+export const ElementType = {
+  // Float vectors
+  V2f:  _V2f, V3f: _V3f, V4f: _V4f,
+  // Float matrices (square)
+  M22f: _M22f, M33f: _M33f, M44f: _M44f,
+  // Signed-int vectors
+  V2i: _V2i, V3i: _V3i, V4i: _V4i,
+  // Unsigned-int vectors
+  V2u: _V2u, V3u: _V3u, V4u: _V4u,
+  // Scalars
+  F32: _F32, U32: _U32, I32: _I32,
+  U16: _U16, I16: _I16, U8: _U8, I8: _I8,
+
+  /** Infer from a wombat.base packed array or a native TypedArray. */
+  fromArray,
+  /** GPUVertexFormat for `t`; throws if `t` has no vertex form. */
+  toVertexFormat: asVertexFormat,
+  /** GPUIndexFormat for `t`; throws if `t` is not `u16` / `u32`. */
+  toIndexFormat:  asIndexFormat,
+} as const;

package/src/core/index.ts

@@ -11,10 +11,15 @@ export type {
   HostBufferSource,
 } from "./buffer.js";
 
-export type {
+export {
   BufferView,
 } from "./bufferView.js";
 
+export {
+  ElementType,
+  ElementKind,
+} 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);
+    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>();
 }
 
 /**