@aardworx/wombat.rendering 0.5.4 → 0.7.0

package/src/core/bufferView.ts

@@ -1,26 +1,277 @@
 // 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.
+// attribute, instance attribute, or index source. Mirrors
+// Aardvark.Rendering's `BufferView`:
 //
-// `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.
+//   - `buffer` is `aval<IBuffer>` so per-frame content changes flow
+//     through normal aval marking without reshaping the view.
+//   - `elementType` carries the element kind; the backend derives
+//     `GPUVertexFormat` / `GPUIndexFormat` and a default stride from
+//     it.
+//   - `singleValue` is set when the view was constructed from a
+//     single adaptive value broadcast to all instances/vertices —
+//     the runtime can lower it to a uniform binding instead of a
+//     per-vertex/per-instance attribute.
+//
+// The view itself is plain (not wrapped in `aval`). Structural
+// fields — `elementType`, `offset`, `stride`, `normalized` — are
+// eager so the binding plan / pipeline layout can be computed
+// without forcing.
 
-import type { IBuffer } from "./buffer.js";
+import type { aval } from "@aardworx/wombat.adaptive";
+import { AVal } from "@aardworx/wombat.adaptive";
+import { IBuffer } from "./buffer.js";
+import type { ElementType } from "./elementType.js";
+import { ElementType as ElementTypeRegistry } from "./elementType.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;
+  /** Adaptive buffer source — content changes flow through this aval. */
+  readonly buffer: aval<IBuffer>;
+  /** Element kind. Stride defaults from this when `stride` is 0/undefined. */
+  readonly elementType: ElementType;
+  /** Byte offset into `buffer` where the view starts. Default 0. */
+  readonly offset?: number;
+  /** Stride between consecutive elements in bytes. 0 = tight (= `byteSize(elementType)`). */
+  readonly stride?: number;
+  /** Integer attributes treated as normalized fixed-point floats. Default false. */
+  readonly normalized?: boolean;
+  /**
+   * Present iff this view was constructed from a single adaptive
+   * value (see `BufferView.ofValue`). Lets the backend lower the
+   * binding to a uniform instead of a per-vertex/per-instance
+   * attribute.
+   */
+  readonly singleValue?: aval<unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Inference helpers — discover ElementType from a wombat.base packed
+// array or a TypedArray. Kept as a duck-type lookup so wombat.base
+// doesn't need to expose explicit brands.
+// ---------------------------------------------------------------------------
+
+interface WombatArrayLike {
+  readonly buffer: ArrayBufferLike;
+  readonly length: number;
+}
+
+function inferElementType(arr: unknown): ElementType {
+  // wombat.base packed types — discover via class name. These all
+  // have a distinct `constructor.name` and a `buffer: ArrayBuffer`
+  // backing field.
+  const ctor = (arr as { constructor?: { name?: string } }).constructor;
+  const name = ctor?.name;
+  switch (name) {
+    case "V2fArray": return "v2f";
+    case "V3fArray": return "v3f";
+    case "V4fArray": return "v4f";
+    case "V2iArray": return "v2i";
+    case "V3iArray": return "v3i";
+    case "V4iArray": return "v4i";
+    case "V2uiArray": return "v2u";
+    case "V3uiArray": return "v3u";
+    case "V4uiArray": return "v4u";
+    // Native typed arrays.
+    case "Float32Array": return "f32";
+    case "Uint32Array":  return "u32";
+    case "Int32Array":   return "i32";
+    case "Uint16Array":  return "u16";
+    case "Int16Array":   return "i16";
+    case "Uint8Array":   return "u8";
+    case "Int8Array":    return "i8";
+  }
+  throw new Error(
+    `BufferView.ofArray: cannot infer ElementType from ${name ?? "unknown type"}; ` +
+    `pass elementType explicitly`,
+  );
+}
+
+function arrayToHostBytes(arr: unknown): ArrayBuffer | ArrayBufferView {
+  // wombat.base packed types expose `.buffer: ArrayBuffer` covering
+  // exactly the packed bytes.
+  const a = arr as { buffer?: unknown };
+  if (a.buffer instanceof ArrayBuffer) return a.buffer;
+  // Native typed array — pass through.
+  if (ArrayBuffer.isView(arr as ArrayBufferView)) return arr as ArrayBufferView;
+  throw new Error("BufferView.ofArray: unsupported array source");
+}
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+interface OfArrayOptions {
+  readonly elementType?: ElementType;
+  readonly offset?: number;
+  readonly stride?: number;
+  readonly normalized?: boolean;
+}
+
+interface OfGPUOptions {
+  readonly offset?: number;
+  readonly stride?: number;
+  readonly normalized?: boolean;
+}
+
+function isAval<T>(v: unknown): v is aval<T> {
+  return typeof v === "object" && v !== null
+    && typeof (v as { getValue?: unknown }).getValue === "function";
+}
+
+export const BufferView = {
+  /**
+   * Build a view from a wombat.base packed array (`V3fArray`,
+   * `Uint16Array`, …) or an `aval<…>` of one. The element type is
+   * inferred from the array constructor; pass it explicitly via
+   * `opts.elementType` for unusual cases.
+   */
+  ofArray<T extends WombatArrayLike | ArrayBufferView>(
+    a: aval<T> | T,
+    opts: OfArrayOptions = {},
+  ): BufferView {
+    const adaptive = isAval<T>(a) ? a : AVal.constant(a);
+    // Determine element type — eager. We force the aval ONCE here
+    // to discover the array kind, which is structural; subsequent
+    // changes are expected to keep the same kind.
+    const sample = adaptive.force(/* allow-force */);
+    const elementType = opts.elementType ?? inferElementType(sample);
+    const buffer = adaptive.map((arr): IBuffer =>
+      IBuffer.fromHost(arrayToHostBytes(arr)),
+    );
+    return {
+      buffer,
+      elementType,
+      ...(opts.offset !== undefined ? { offset: opts.offset } : {}),
+      ...(opts.stride !== undefined ? { stride: opts.stride } : {}),
+      ...(opts.normalized !== undefined ? { normalized: opts.normalized } : {}),
+    };
+  },
+
+  /**
+   * Build a view that broadcasts a single adaptive value to every
+   * vertex / instance. The runtime detects the `singleValue` field
+   * and lowers it to a uniform binding instead of a per-element
+   * attribute. The `buffer` aval still carries packed bytes for
+   * backends that don't recognize the fast path.
+   */
+  ofValue<T>(
+    v: aval<T> | T,
+    elementType: ElementType,
+  ): BufferView {
+    const adaptive = isAval<T>(v) ? v : AVal.constant(v);
+    const buffer = adaptive.map((value): IBuffer => {
+      const bytes = ElementTypeRegistry.byteSize(elementType);
+      const ab = new ArrayBuffer(bytes);
+      packSingle(value, elementType, ab);
+      return IBuffer.fromHost(ab);
+    });
+    return {
+      buffer,
+      elementType,
+      singleValue: adaptive,
+    };
+  },
+
+  /**
+   * Build a view backed by a user-supplied `GPUBuffer`. The
+   * runtime binds it directly without an upload step.
+   */
+  ofGPU(
+    buffer: aval<GPUBuffer> | GPUBuffer,
+    elementType: ElementType,
+    opts: OfGPUOptions = {},
+  ): BufferView {
+    const adaptive = isAval<GPUBuffer>(buffer) ? buffer : AVal.constant(buffer);
+    const ibuffer = adaptive.map((b): IBuffer => IBuffer.fromGPU(b));
+    return {
+      buffer: ibuffer,
+      elementType,
+      ...(opts.offset !== undefined ? { offset: opts.offset } : {}),
+      ...(opts.stride !== undefined ? { stride: opts.stride } : {}),
+      ...(opts.normalized !== undefined ? { normalized: opts.normalized } : {}),
+    };
+  },
+
+  /**
+   * Wrap an already-built `aval<IBuffer>` with explicit element
+   * type. Used by callers that compute their own `IBuffer` (e.g.
+   * compositing multiple attributes into one packed buffer).
+   */
+  ofBuffer(
+    buffer: aval<IBuffer>,
+    elementType: ElementType,
+    opts: OfGPUOptions = {},
+  ): BufferView {
+    return {
+      buffer,
+      elementType,
+      ...(opts.offset !== undefined ? { offset: opts.offset } : {}),
+      ...(opts.stride !== undefined ? { stride: opts.stride } : {}),
+      ...(opts.normalized !== undefined ? { normalized: opts.normalized } : {}),
+    };
+  },
+
+  // ---------- accessors ----------
+
+  /** Byte offset, defaulting to 0. */
+  offsetOf(v: BufferView): number { return v.offset ?? 0; },
+  /**
+   * Stride in bytes — `v.stride` if set and non-zero, otherwise
+   * tight from `elementType`.
+   */
+  strideOf(v: BufferView): number {
+    return v.stride !== undefined && v.stride > 0
+      ? v.stride
+      : ElementTypeRegistry.byteSize(v.elementType);
+  },
+  /** Whether this view is a single-value broadcast. */
+  isSingleValue(v: BufferView): boolean {
+    return v.singleValue !== undefined;
+  },
+} as const;
+
+// ---------------------------------------------------------------------------
+// Single-value packing — write one element of `elementType` into a
+// fresh ArrayBuffer. The runtime usually shortcuts this via
+// `singleValue` (lifted to a uniform), so this path runs only for
+// backends that don't recognize the broadcast.
+// ---------------------------------------------------------------------------
+
+function packSingle(value: unknown, t: ElementType, dst: ArrayBuffer): void {
+  // Lazy import to avoid a hard dep on wombat.base shapes here. We
+  // peek at `_data` (the typed-array view exposed by every wombat
+  // math type) and copy its bytes into the destination.
+  const v = value as { _data?: ArrayLike<number> };
+  if (v._data !== undefined) {
+    const src = v._data;
+    switch (t) {
+      case "v2f": case "v3f": case "v4f":
+      case "m22f": case "m33f": case "m44f":
+      case "f32": {
+        const out = new Float32Array(dst);
+        for (let i = 0; i < src.length; i++) out[i] = src[i]!;
+        return;
+      }
+      case "v2i": case "v3i": case "v4i": case "i32": {
+        const out = new Int32Array(dst);
+        for (let i = 0; i < src.length; i++) out[i] = src[i]!;
+        return;
+      }
+      case "v2u": case "v3u": case "v4u": case "u32": {
+        const out = new Uint32Array(dst);
+        for (let i = 0; i < src.length; i++) out[i] = src[i]!;
+        return;
+      }
+    }
+  }
+  // Scalars and unbranded values.
+  switch (t) {
+    case "f32": new Float32Array(dst)[0] = value as number; return;
+    case "u32": new Uint32Array(dst)[0]  = value as number; return;
+    case "i32": new Int32Array(dst)[0]   = value as number; return;
+    case "u16": new Uint16Array(dst)[0]  = value as number; return;
+    case "i16": new Int16Array(dst)[0]   = value as number; return;
+    case "u8":  new Uint8Array(dst)[0]   = value as number; return;
+    case "i8":  new Int8Array(dst)[0]    = value as number; return;
+  }
+  throw new Error(`BufferView.ofValue: cannot pack ${typeof value} as ${t}`);
 }

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>;
 }