@vib3code/sdk 2.0.1

package/src/ui/adaptive/renderers/webgpu/BufferLayout.ts

@@ -0,0 +1,252 @@
+export type LayoutMode = 'std140' | 'std430';
+
+export type LayoutFieldType = 'f32' | 'vec2' | 'vec3' | 'vec4' | 'mat4x4';
+
+export interface LayoutFieldDefinition {
+  readonly name: string;
+  readonly type: LayoutFieldType;
+  /** Number of elements for arrays. Defaults to 1. */
+  readonly count?: number;
+}
+
+export interface LayoutField {
+  readonly name: string;
+  readonly type: LayoutFieldType;
+  readonly count: number;
+  /** Byte offset from the start of the struct. */
+  readonly offset: number;
+  /** Total byte span occupied by the field including padding. */
+  readonly size: number;
+  /** Byte distance between array elements (equals size when count === 1). */
+  readonly stride: number;
+  /** Number of numeric components per element (e.g. vec3 → 3). */
+  readonly componentCount: number;
+}
+
+export interface BufferLayout {
+  readonly mode: LayoutMode;
+  readonly byteSize: number;
+  readonly fields: Readonly<Record<string, LayoutField>>;
+}
+
+export interface WriteFieldOptions {
+  /** Index of the array element to write (defaults to 0). */
+  readonly elementIndex?: number;
+  /** Number of array elements that will be written from the provided values. */
+  readonly elementCount?: number;
+}
+
+const COMPONENT_COUNT: Record<LayoutFieldType, number> = {
+  f32: 1,
+  vec2: 2,
+  vec3: 3,
+  vec4: 4,
+  mat4x4: 16,
+};
+
+const NATURAL_SIZE: Record<LayoutFieldType, number> = {
+  f32: 4,
+  vec2: 8,
+  vec3: 12,
+  vec4: 16,
+  mat4x4: 64,
+};
+
+const BASE_ALIGNMENT: Record<LayoutFieldType, number> = {
+  f32: 4,
+  vec2: 8,
+  vec3: 16,
+  vec4: 16,
+  mat4x4: 16,
+};
+
+function align(value: number, alignment: number): number {
+  return Math.ceil(value / alignment) * alignment;
+}
+
+function resolveCount(def: LayoutFieldDefinition): number {
+  const count = Math.floor(def.count ?? 1);
+  if (count <= 0) {
+    throw new Error(`Field "${def.name}" requires a positive element count.`);
+  }
+  return count;
+}
+
+function computeArrayAlignment(mode: LayoutMode, baseAlignment: number): number {
+  if (mode === 'std140') {
+    return Math.max(baseAlignment, 16);
+  }
+  return baseAlignment;
+}
+
+function computeStride(mode: LayoutMode, type: LayoutFieldType, arrayAlignment: number): number {
+  const natural = NATURAL_SIZE[type];
+  if (mode === 'std140') {
+    return align(natural, arrayAlignment);
+  }
+  return align(natural, arrayAlignment);
+}
+
+function computeElementSize(type: LayoutFieldType): number {
+  const baseAlignment = BASE_ALIGNMENT[type];
+  return align(NATURAL_SIZE[type], baseAlignment);
+}
+
+function createLayout(mode: LayoutMode, definitions: readonly LayoutFieldDefinition[]): BufferLayout {
+  let size = 0;
+  const fields: Record<string, LayoutField> = {};
+
+  for (const def of definitions) {
+    if (!def?.name) {
+      throw new Error('Layout fields require a name.');
+    }
+    if (!COMPONENT_COUNT[def.type]) {
+      throw new Error(`Unsupported field type "${String(def.type)}" for ${def.name}.`);
+    }
+
+    const baseAlignment = BASE_ALIGNMENT[def.type];
+    const count = resolveCount(def);
+    const componentCount = COMPONENT_COUNT[def.type];
+
+    if (count > 1) {
+      const arrayAlignment = computeArrayAlignment(mode, baseAlignment);
+      size = align(size, arrayAlignment);
+      const stride = computeStride(mode, def.type, arrayAlignment);
+      const fieldSize = stride * count;
+      fields[def.name] = {
+        name: def.name,
+        type: def.type,
+        count,
+        offset: size,
+        size: fieldSize,
+        stride,
+        componentCount,
+      };
+      size += fieldSize;
+    } else {
+      size = align(size, baseAlignment);
+      const elementSize = computeElementSize(def.type);
+      fields[def.name] = {
+        name: def.name,
+        type: def.type,
+        count,
+        offset: size,
+        size: elementSize,
+        stride: elementSize,
+        componentCount,
+      };
+      size += elementSize;
+    }
+  }
+
+  const byteSize = align(size, 16);
+  return Object.freeze({
+    mode,
+    byteSize,
+    fields: Object.freeze(fields),
+  });
+}
+
+export function createStd140Layout(definitions: readonly LayoutFieldDefinition[]): BufferLayout {
+  return createLayout('std140', definitions);
+}
+
+export function createStd430Layout(definitions: readonly LayoutFieldDefinition[]): BufferLayout {
+  return createLayout('std430', definitions);
+}
+
+export function createFloat32ArrayForLayout(layout: BufferLayout): Float32Array {
+  return new Float32Array(layout.byteSize / Float32Array.BYTES_PER_ELEMENT);
+}
+
+function ensureTargetSize(layout: BufferLayout, target: Float32Array): void {
+  if (target.length * Float32Array.BYTES_PER_ELEMENT < layout.byteSize) {
+    throw new Error('Target buffer is too small for the provided layout.');
+  }
+}
+
+export function writeField(
+  layout: BufferLayout,
+  target: Float32Array,
+  fieldName: string,
+  values: ArrayLike<number>,
+  options: WriteFieldOptions = {}
+): void {
+  ensureTargetSize(layout, target);
+  const field = layout.fields[fieldName];
+  if (!field) {
+    throw new Error(`Unknown field "${fieldName}" in layout.`);
+  }
+
+  const elementCount = Math.min(field.count, Math.floor(options.elementCount ?? field.count));
+  if (elementCount <= 0) {
+    return;
+  }
+  const elementIndex = Math.min(field.count - 1, Math.max(0, Math.floor(options.elementIndex ?? 0)));
+  const components = field.componentCount;
+  const strideFloats = field.stride / Float32Array.BYTES_PER_ELEMENT;
+  const offsetFloats = field.offset / Float32Array.BYTES_PER_ELEMENT + elementIndex * strideFloats;
+
+  const requiredValues = components * elementCount;
+  if (values.length < requiredValues) {
+    throw new Error(`Field "${fieldName}" requires at least ${requiredValues} components.`);
+  }
+
+  let cursor = 0;
+  for (let element = 0; element < elementCount; element += 1) {
+    const base = offsetFloats + element * strideFloats;
+    for (let i = 0; i < components; i += 1) {
+      target[base + i] = values[cursor + i];
+    }
+    for (let i = components; i < strideFloats; i += 1) {
+      target[base + i] = 0;
+    }
+    cursor += components;
+  }
+
+  const remaining = field.count - (elementIndex + elementCount);
+  if (remaining > 0) {
+    const base = offsetFloats + elementCount * strideFloats;
+    const total = remaining * strideFloats;
+    for (let i = 0; i < total; i += 1) {
+      target[base + i] = 0;
+    }
+  }
+}
+
+export function readField(
+  layout: BufferLayout,
+  source: Float32Array,
+  fieldName: string,
+  options: WriteFieldOptions = {}
+): Float32Array {
+  ensureTargetSize(layout, source);
+  const field = layout.fields[fieldName];
+  if (!field) {
+    throw new Error(`Unknown field "${fieldName}" in layout.`);
+  }
+  const elementIndex = Math.min(field.count - 1, Math.max(0, Math.floor(options.elementIndex ?? 0)));
+  const elementCount = Math.min(field.count - elementIndex, Math.floor(options.elementCount ?? 1));
+  const strideFloats = field.stride / Float32Array.BYTES_PER_ELEMENT;
+  const offsetFloats = field.offset / Float32Array.BYTES_PER_ELEMENT + elementIndex * strideFloats;
+  const result = new Float32Array(field.componentCount * elementCount);
+  for (let element = 0; element < elementCount; element += 1) {
+    const base = offsetFloats + element * strideFloats;
+    for (let i = 0; i < field.componentCount; i += 1) {
+      result[element * field.componentCount + i] = source[base + i];
+    }
+  }
+  return result;
+}
+
+export const GlassUniformLayout = createStd140Layout([
+  { name: 'leftViewProj', type: 'mat4x4' },
+  { name: 'rightViewProj', type: 'mat4x4' },
+  { name: 'headMatrix', type: 'mat4x4' },
+  { name: 'rotor4d', type: 'vec4' },
+  { name: 'euler', type: 'vec4' },
+  { name: 'metrics', type: 'vec4' },
+  { name: 'audio', type: 'vec4' },
+  { name: 'localization', type: 'vec4' },
+  { name: 'visual', type: 'vec4' },
+]);

package/src/ui/adaptive/renderers/webgpu/PolytopeInstanceBuffer.ts

@@ -0,0 +1,144 @@
+import { createStd430Layout, createFloat32ArrayForLayout, writeField, readField, type BufferLayout } from './BufferLayout.ts';
+import type { GPUBufferLike, GPUDeviceLike, GPUQueueLike } from './TripleBufferedUniform.ts';
+
+const GPU_BUFFER_USAGE_STORAGE = 0x20;
+const GPU_BUFFER_USAGE_COPY_DST = 0x8;
+
+export interface PolytopeInstance {
+  readonly modelMatrix: ArrayLike<number>;
+  readonly rotor: ArrayLike<number>;
+  readonly color: ArrayLike<number>;
+  readonly misc?: {
+    readonly scale?: number;
+    readonly audioEnergy?: number;
+    readonly glitch?: number;
+    readonly id?: number;
+  };
+}
+
+export interface PolytopeInstanceBufferOptions {
+  readonly device: GPUDeviceLike;
+  readonly maxInstances: number;
+  readonly label?: string;
+  readonly usage?: number;
+}
+
+export interface InstanceWriteOptions {
+  readonly index: number;
+}
+
+export class PolytopeInstanceBuffer {
+  readonly device: GPUDeviceLike;
+  readonly layout: BufferLayout;
+  readonly maxInstances: number;
+  readonly label: string;
+  readonly buffer: GPUBufferLike;
+  readonly data: Float32Array;
+
+  private instanceCount = 0;
+
+  constructor(options: PolytopeInstanceBufferOptions) {
+    if (!options?.device) {
+      throw new Error('PolytopeInstanceBuffer requires a WebGPU-compatible device.');
+    }
+    if (!Number.isFinite(options.maxInstances) || options.maxInstances <= 0) {
+      throw new Error('PolytopeInstanceBuffer maxInstances must be a positive integer.');
+    }
+
+    this.device = options.device;
+    this.maxInstances = Math.floor(options.maxInstances);
+    this.label = options.label ?? 'PolytopeInstanceBuffer';
+
+    this.layout = createStd430Layout([
+      { name: 'modelMatrices', type: 'mat4x4', count: this.maxInstances },
+      { name: 'rotors', type: 'vec4', count: this.maxInstances },
+      { name: 'colors', type: 'vec4', count: this.maxInstances },
+      { name: 'misc', type: 'vec4', count: this.maxInstances },
+    ]);
+
+    this.data = createFloat32ArrayForLayout(this.layout);
+
+    const usage = options.usage ?? (GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST);
+    this.buffer = this.device.createBuffer({
+      size: this.layout.byteSize,
+      usage,
+      label: `${this.label}-storage`,
+    });
+  }
+
+  get count(): number {
+    return this.instanceCount;
+  }
+
+  reset(): void {
+    this.instanceCount = 0;
+    this.data.fill(0);
+  }
+
+  writeInstance(instance: PolytopeInstance, options: InstanceWriteOptions): void {
+    const index = Math.floor(options.index);
+    if (index < 0 || index >= this.maxInstances) {
+      throw new Error(`Instance index ${index} is out of bounds for maxInstances=${this.maxInstances}.`);
+    }
+
+    writeField(this.layout, this.data, 'modelMatrices', ensureLength(instance.modelMatrix, 16), {
+      elementIndex: index,
+      elementCount: 1,
+    });
+
+    const rotor = ensureLength(instance.rotor, 4);
+    writeField(this.layout, this.data, 'rotors', rotor, { elementIndex: index, elementCount: 1 });
+
+    const color = ensureLength(instance.color, 4);
+    writeField(this.layout, this.data, 'colors', color, { elementIndex: index, elementCount: 1 });
+
+    const misc = buildMisc(instance.misc);
+    writeField(this.layout, this.data, 'misc', misc, { elementIndex: index, elementCount: 1 });
+
+    this.instanceCount = Math.max(this.instanceCount, index + 1);
+  }
+
+  readInstance(index: number): { modelMatrix: Float32Array; rotor: Float32Array; color: Float32Array; misc: Float32Array } {
+    if (index < 0 || index >= this.maxInstances) {
+      throw new Error(`Instance index ${index} is out of bounds for maxInstances=${this.maxInstances}.`);
+    }
+    return {
+      modelMatrix: readField(this.layout, this.data, 'modelMatrices', { elementIndex: index }),
+      rotor: readField(this.layout, this.data, 'rotors', { elementIndex: index }),
+      color: readField(this.layout, this.data, 'colors', { elementIndex: index }),
+      misc: readField(this.layout, this.data, 'misc', { elementIndex: index }),
+    };
+  }
+
+  upload(queue: GPUQueueLike = this.device.queue): void {
+    if (!queue || typeof queue.writeBuffer !== 'function') {
+      throw new Error('PolytopeInstanceBuffer.upload requires a valid GPU queue.');
+    }
+    queue.writeBuffer(this.buffer, 0, this.data);
+  }
+
+  bindGroupEntry(binding = 0): { binding: number; resource: { buffer: GPUBufferLike } } {
+    return { binding, resource: { buffer: this.buffer } };
+  }
+}
+
+function ensureLength(values: ArrayLike<number>, expected: number): Float32Array {
+  const result = new Float32Array(expected);
+  const length = Math.min(values.length, expected);
+  for (let i = 0; i < length; i += 1) {
+    result[i] = Number(values[i]) || 0;
+  }
+  return result;
+}
+
+function buildMisc(misc: PolytopeInstance['misc']): Float32Array {
+  const result = new Float32Array(4);
+  if (!misc) {
+    return result;
+  }
+  result[0] = Number(misc.scale) || 0;
+  result[1] = Number(misc.audioEnergy) || 0;
+  result[2] = Number(misc.glitch) || 0;
+  result[3] = Number(misc.id) || 0;
+  return result;
+}

package/src/ui/adaptive/renderers/webgpu/TripleBufferedUniform.ts

@@ -0,0 +1,170 @@
+/**
+ * Triple-buffered uniform buffer for WebGPU
+ * Provides smooth animation by maintaining 3 buffers for CPU write, GPU read, and swap
+ */
+
+// Type definitions for WebGPU-like interfaces (compatible with actual WebGPU or mocks)
+export interface GPUBufferLike {
+    readonly size: number;
+    readonly usage: number;
+    readonly label?: string;
+    mapAsync?: (mode: number) => Promise<void>;
+    getMappedRange?: () => ArrayBuffer;
+    unmap?: () => void;
+    destroy?: () => void;
+}
+
+export interface GPUDeviceLike {
+    readonly queue: GPUQueueLike;
+    createBuffer(descriptor: {
+        size: number;
+        usage: number;
+        label?: string;
+        mappedAtCreation?: boolean;
+    }): GPUBufferLike;
+    createBindGroup?(descriptor: unknown): unknown;
+    createBindGroupLayout?(descriptor: unknown): unknown;
+}
+
+export interface GPUQueueLike {
+    writeBuffer(buffer: GPUBufferLike, offset: number, data: ArrayBufferView | ArrayBuffer): void;
+    submit?(commandBuffers: unknown[]): void;
+}
+
+export interface TripleBufferedUniformOptions {
+    readonly device: GPUDeviceLike;
+    readonly byteSize: number;
+    readonly label?: string;
+}
+
+const GPU_BUFFER_USAGE_UNIFORM = 0x40;
+const GPU_BUFFER_USAGE_COPY_DST = 0x8;
+
+/**
+ * Triple-buffered uniform buffer for smooth animations
+ * - Buffer 0: Currently being written by CPU
+ * - Buffer 1: Staged for next GPU read
+ * - Buffer 2: Currently being read by GPU
+ */
+export class TripleBufferedUniform {
+    readonly device: GPUDeviceLike;
+    readonly byteSize: number;
+    readonly label: string;
+    readonly buffers: [GPUBufferLike, GPUBufferLike, GPUBufferLike];
+    readonly data: Float32Array;
+
+    private writeIndex = 0;
+    private readIndex = 2;
+
+    constructor(options: TripleBufferedUniformOptions) {
+        if (!options?.device) {
+            throw new Error('TripleBufferedUniform requires a WebGPU-compatible device.');
+        }
+        if (!Number.isFinite(options.byteSize) || options.byteSize <= 0) {
+            throw new Error('TripleBufferedUniform byteSize must be a positive number.');
+        }
+
+        this.device = options.device;
+        // Align to 256 bytes (WebGPU requirement for uniform buffers)
+        this.byteSize = Math.ceil(options.byteSize / 256) * 256;
+        this.label = options.label ?? 'TripleBufferedUniform';
+
+        // Create CPU-side data buffer
+        this.data = new Float32Array(this.byteSize / Float32Array.BYTES_PER_ELEMENT);
+
+        // Create three GPU buffers
+        this.buffers = [
+            this.createBuffer(0),
+            this.createBuffer(1),
+            this.createBuffer(2)
+        ];
+    }
+
+    private createBuffer(index: number): GPUBufferLike {
+        return this.device.createBuffer({
+            size: this.byteSize,
+            usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+            label: `${this.label}-${index}`
+        });
+    }
+
+    /**
+     * Get the buffer currently available for GPU reading
+     */
+    get currentBuffer(): GPUBufferLike {
+        return this.buffers[this.readIndex];
+    }
+
+    /**
+     * Write data to the current write buffer and rotate
+     * @param queue - GPU queue for buffer upload
+     */
+    upload(queue: GPUQueueLike = this.device.queue): void {
+        if (!queue || typeof queue.writeBuffer !== 'function') {
+            throw new Error('TripleBufferedUniform.upload requires a valid GPU queue.');
+        }
+
+        // Write to current write buffer
+        queue.writeBuffer(this.buffers[this.writeIndex], 0, this.data);
+
+        // Rotate indices
+        const oldWrite = this.writeIndex;
+        this.writeIndex = (this.writeIndex + 1) % 3;
+        this.readIndex = oldWrite;
+    }
+
+    /**
+     * Write a float value at the specified offset
+     */
+    writeFloat(offset: number, value: number): void {
+        const index = Math.floor(offset / Float32Array.BYTES_PER_ELEMENT);
+        if (index >= 0 && index < this.data.length) {
+            this.data[index] = value;
+        }
+    }
+
+    /**
+     * Write a vec4 at the specified offset
+     */
+    writeVec4(offset: number, values: ArrayLike<number>): void {
+        const startIndex = Math.floor(offset / Float32Array.BYTES_PER_ELEMENT);
+        for (let i = 0; i < 4 && i < values.length; i++) {
+            if (startIndex + i < this.data.length) {
+                this.data[startIndex + i] = values[i];
+            }
+        }
+    }
+
+    /**
+     * Write a mat4x4 at the specified offset
+     */
+    writeMat4(offset: number, values: ArrayLike<number>): void {
+        const startIndex = Math.floor(offset / Float32Array.BYTES_PER_ELEMENT);
+        for (let i = 0; i < 16 && i < values.length; i++) {
+            if (startIndex + i < this.data.length) {
+                this.data[startIndex + i] = values[i];
+            }
+        }
+    }
+
+    /**
+     * Create a bind group entry for this buffer
+     */
+    bindGroupEntry(binding = 0): { binding: number; resource: { buffer: GPUBufferLike } } {
+        return {
+            binding,
+            resource: { buffer: this.currentBuffer }
+        };
+    }
+
+    /**
+     * Destroy all buffers
+     */
+    destroy(): void {
+        for (const buffer of this.buffers) {
+            if (buffer.destroy) {
+                buffer.destroy();
+            }
+        }
+    }
+}