@tapez/core 0.0.0-alpha.2 → 0.0.0-alpha.4

package/README.md

@@ -0,0 +1,33 @@
+# @tapez/core
+
+Typed GPU schema system for WebGPU.
+
+Define a GPU struct once — get a type-safe buffer wrapper **and** the WGSL struct definition, guaranteed to stay in sync.
+
+```ts
+import * as tapez from '@tapez/core'
+
+const RowsConfig = tapez.struct('RowsConfig', {
+  midPrice: tapez.f32,
+  rowHeight: tapez.f32,
+  decimals: tapez.u32,
+})
+
+// In your entity:
+const buf = tapez.TypedBuffer.createUniform(device, RowsConfig, 'config')
+buf.set.midPrice(50000.5)
+buf.set.decimals(2)
+buf.writeIfDirty(queue)
+```
+
+The same schema emits a WGSL struct via `RowsConfig.toWGSL()`, consumable in shaders through [`@tapez/vite`](../vite)'s `@import` syntax.
+
+## Contents
+
+- **Schemas** — `f32`, `u32`, `i32`, `vec2f/3f/4f`, `mat2x2f/3x3f/4x4f`, `struct`, `arrayOf`, `const`, `atomic`
+- **TypedBuffer** — named setters, dirty tracking, factory methods
+- **Bind helpers** — `uniformEntry`, `storageEntry`, `bufferEntry`
+
+## Status
+
+Alpha. API may change.

package/dist/index.d.ts

@@ -1,29 +1,397 @@
 /**
- * @tapez/core — Typed GPU schema system for WebGPU.
+ * TapeZ type system — GPU data type definitions.
  *
- * Usage:
- *   import * as tapez from '@tapez/core'
+ * Each type carries its WGSL name, byte size, and alignment
+ * following the WGSL specification for host-shareable types.
+ */
+interface TapezType {
+    /** Unique tag for runtime discrimination */
+    readonly kind: string;
+    /** WGSL type name, e.g. 'f32', 'vec4<f32>' */
+    readonly wgslType: string;
+    /** Byte size of this type in a buffer */
+    readonly byteSize: number;
+    /** Required alignment in bytes (WGSL spec) */
+    readonly alignment: number;
+}
+interface TapezScalar extends TapezType {
+    readonly kind: 'scalar';
+    /** Which typed array setter to use */
+    readonly arrayKind: 'f32' | 'u32' | 'i32';
+}
+declare const f32: TapezScalar;
+declare const u32: TapezScalar;
+declare const i32: TapezScalar;
+interface TapezAtomic extends TapezType {
+    readonly kind: 'atomic';
+    /** The wrapped scalar type */
+    readonly inner: TapezScalar;
+    /** Which typed array setter to use (same as inner) */
+    readonly arrayKind: 'f32' | 'u32' | 'i32';
+}
+declare function atomic(inner: TapezScalar): TapezAtomic;
+
+/**
+ * TapeZ vector types — vec2, vec3, vec4 for f32/u32/i32.
+ *
+ * WGSL alignment rules:
+ *   vec2<T> → size 8,  align 8
+ *   vec3<T> → size 12, align 16
+ *   vec4<T> → size 16, align 16
+ */
+
+interface TapezVector extends TapezType {
+    readonly kind: 'vector';
+    /** Number of components (2, 3, or 4) */
+    readonly components: number;
+    /** Component scalar type */
+    readonly componentType: TapezScalar;
+}
+declare const vec2f: TapezVector;
+declare const vec3f: TapezVector;
+declare const vec4f: TapezVector;
+declare const vec2u: TapezVector;
+declare const vec3u: TapezVector;
+declare const vec4u: TapezVector;
+declare const vec2i: TapezVector;
+declare const vec3i: TapezVector;
+declare const vec4i: TapezVector;
+
+/**
+ * TapeZ matrix types — mat2x2f, mat3x3f, mat4x4f.
+ *
+ * WGSL matrices are column-major arrays of column vectors.
+ *   mat2x2<f32> → 2 columns of vec2<f32> → size 16,  align 8
+ *   mat3x3<f32> → 3 columns of vec3<f32> → size 48,  align 16
+ *   mat4x4<f32> → 4 columns of vec4<f32> → size 64,  align 16
+ */
+
+interface TapezMatrix extends TapezType {
+    readonly kind: 'matrix';
+    /** Number of columns */
+    readonly columns: number;
+    /** Number of rows */
+    readonly rows: number;
+}
+declare const mat2x2f: TapezMatrix;
+declare const mat3x3f: TapezMatrix;
+declare const mat4x4f: TapezMatrix;
+
+/**
+ * WGSL struct layout computation — alignment, padding, field offsets.
+ *
+ * Implements the WGSL spec's struct layout algorithm:
+ * https://www.w3.org/TR/WGSL/#structure-member-layout
+ */
+
+/** Round `offset` up to the next multiple of `alignment`. */
+declare function roundUp(alignment: number, offset: number): number;
+interface FieldLayout {
+    /** Field name */
+    readonly name: string;
+    /** Field type */
+    readonly type: TapezType;
+    /** Byte offset from struct start */
+    readonly offset: number;
+}
+interface StructLayout {
+    /** Ordered field layouts */
+    readonly fields: readonly FieldLayout[];
+    /** Total byte size (padded to struct alignment) */
+    readonly byteSize: number;
+    /** Struct alignment = max(field alignments) */
+    readonly alignment: number;
+    /** Map from field name to byte offset */
+    readonly offsets: Record<string, number>;
+}
+/**
+ * Compute the byte layout of a struct given its fields in order.
+ * Follows WGSL struct member layout rules.
+ */
+declare function computeStructLayout(fields: readonly {
+    name: string;
+    type: TapezType;
+}[]): StructLayout;
+
+/**
+ * TapeZ struct definition — the core of the schema system.
  *
+ * Usage:
  *   const MyConfig = tapez.struct('MyConfig', {
  *     midPrice: tapez.f32,
+ *     rowHeight: tapez.f32,
  *     decimals: tapez.u32,
- *     color: tapez.vec4f,
  *   })
+ *
+ *   MyConfig.byteSize    // 12
+ *   MyConfig.offsets      // { midPrice: 0, rowHeight: 4, decimals: 8 }
+ *   MyConfig.toWGSL()    // "struct MyConfig {\n  midPrice: f32,\n  ..."
+ */
+
+interface TapezStruct<F extends Record<string, TapezType> = Record<string, TapezType>> extends TapezType {
+    readonly kind: 'struct';
+    /** Struct name (used in WGSL output) */
+    readonly name: string;
+    /** Field type definitions, keyed by name */
+    readonly fields: F;
+    /** Byte offset of each field */
+    readonly offsets: {
+        readonly [K in keyof F]: number;
+    };
+    /** Field names in definition order */
+    readonly fieldOrder: readonly (keyof F & string)[];
+    /** Full computed layout with per-field metadata */
+    readonly layout: StructLayout;
+    /** Generate WGSL struct declaration */
+    toWGSL(): string;
+    /**
+     * Create a new struct with specified fields wrapped in atomic<>.
+     * Same memory layout — atomic<u32> and u32 are identical in size/alignment.
+     * Only u32 and i32 fields can be made atomic.
+     */
+    withAtomics<K extends keyof F & string>(name: string, atomicFields: K[]): TapezStruct<F>;
+}
+/**
+ * Define a GPU struct schema.
+ *
+ * Fields are laid out in definition order following WGSL alignment rules.
+ * The returned object is frozen and can be shared across entities.
+ */
+declare function struct<F extends Record<string, TapezType>>(name: string, fields: F): TapezStruct<F>;
+
+/**
+ * TapeZ array type — fixed-size GPU arrays.
+ *
+ * WGSL array layout:
+ *   Element stride = roundUp(alignment, sizeof(element))
+ *   Array size     = count * stride
+ *   Array alignment = element alignment
+ */
+
+interface TapezArray extends TapezType {
+    readonly kind: 'array';
+    /** Element type */
+    readonly elementType: TapezType;
+    /** Number of elements */
+    readonly count: number;
+    /** Byte stride between consecutive elements (includes padding) */
+    readonly stride: number;
+}
+/**
+ * Define a fixed-size GPU array.
+ *
+ * Element stride follows WGSL array layout rules:
+ * stride = roundUp(element.alignment, element.byteSize)
+ */
+declare function arrayOf(elementType: TapezType, count: number): TapezArray;
+
+/**
+ * TapeZ constants — shared between TypeScript and WGSL.
+ *
+ * Usage:
+ *   const MAX_ROWS = tapez.const('MAX_ROWS', tapez.u32, 4096)
+ *
+ *   MAX_ROWS.value     // 4096 (use in TypeScript)
+ *   MAX_ROWS.toWGSL()  // 'const MAX_ROWS: u32 = 4096u;' (injected into WGSL)
+ */
+
+interface TapezConst<T extends TapezScalar = TapezScalar> {
+    readonly kind: 'const';
+    /** Constant name (used in both TS and WGSL) */
+    readonly name: string;
+    /** Scalar type */
+    readonly type: T;
+    /** The value */
+    readonly value: number;
+    /** Generate WGSL const declaration */
+    toWGSL(): string;
+}
+/**
+ * Define a shared constant available in both TypeScript and WGSL.
+ */
+declare function constant<T extends TapezScalar>(name: string, type: T, value: number): TapezConst<T>;
+
+declare class UniformBuffer {
+    readonly buffer: GPUBuffer;
+    readonly scratch: ArrayBuffer;
+    readonly u32: Uint32Array;
+    readonly i32: Int32Array;
+    readonly f32: Float32Array;
+    readonly byteSize: number;
+    constructor(device: GPUDevice, label: string, byteSize: number, usage?: GPUBufferUsageFlags);
+    write(queue: GPUQueue, offsetBytes?: number): void;
+    destroy(): void;
+}
+/**
+ * UniformBuffer with dirty tracking for conditional GPU uploads.
+ * Use set* methods to write values - they only mark dirty if value changed.
+ * Call writeIfDirty(queue) once per frame to upload if any values changed.
+ *
+ * Eliminates boilerplate "cache field + comparison + write" patterns in entities.
+ */
+declare class DirtyUniformBuffer extends UniformBuffer {
+    private _dirty;
+    /** Set a u32 value at index, marks dirty only if value changed */
+    setU32(i: number, v: number): void;
+    /** Set an i32 value at index, marks dirty only if value changed */
+    setI32(i: number, v: number): void;
+    /** Set an f32 value at index, marks dirty only if value changed */
+    setF32(i: number, v: number): void;
+    /** Force dirty state (use when external factors require re-upload) */
+    markDirty(): void;
+    /** Returns true if any values have changed since last write */
+    get isDirty(): boolean;
+    /** Upload to GPU only if dirty, then clear dirty flag */
+    writeIfDirty(queue: GPUQueue, offsetBytes?: number): void;
+}
+
+/**
+ * TypedBuffer — GPU buffer backed by a tapez type.
+ *
+ * Accepts any TapezType: scalars, vectors, arrays, structs.
+ * For structs, provides named field setters/getters with dirty tracking.
+ * For all types, provides the raw GPUBuffer, typed array views, and lifecycle.
+ *
+ * Usage:
+ *   // Struct — named setters
+ *   const config = TypedBuffer.createUniform(device, MyStruct, 'config')
+ *   config.set.midPrice(1.5)
+ *   config.writeIfDirty(queue)
+ *
+ *   // Array — raw typed array access
+ *   const rows = TypedBuffer.createStorage(device, tapez.arrayOf(tapez.f32, 4096), 'rows')
+ *   rows.raw.f32.set(myData)
+ *   rows.write(queue)
+ *
+ *   // Indirect draw
+ *   const indirect = TypedBuffer.createIndirect(device, IndirectDraw, 'indirect')
+ */
+
+/** Maps a TapezType to its TypeScript setter value type */
+type SetterValue<T extends TapezType> = T extends TapezScalar | TapezAtomic ? number : T extends TapezVector ? number[] | Float32Array | Uint32Array | Int32Array : number[] | Float32Array;
+/** Setter functions keyed by field name */
+type Setters<F extends Record<string, TapezType>> = {
+    readonly [K in keyof F]: (value: SetterValue<F[K]>) => void;
+};
+/** Getter functions keyed by field name */
+type Getters<F extends Record<string, TapezType>> = {
+    readonly [K in keyof F]: () => SetterValue<F[K]>;
+};
+/** Extract the fields type from a TapezStruct, or never */
+type FieldsOf<T extends TapezType> = T extends TapezStruct<infer F> ? F : never;
+interface TypedBufferBase {
+    readonly buffer: GPUBuffer;
+    readonly byteSize: number;
+    readonly isDirty: boolean;
+    markDirty(): void;
+    writeIfDirty(queue: GPUQueue): void;
+    write(queue: GPUQueue): void;
+    writeRaw(queue: GPUQueue, data: BufferSource | SharedArrayBuffer, bufferOffset?: number, dataOffset?: number, size?: number): void;
+    copyTo(encoder: GPUCommandEncoder, dest: TypedBufferBase, srcOffset?: number, dstOffset?: number, size?: number): void;
+    copyFrom(encoder: GPUCommandEncoder, src: TypedBufferBase, srcOffset?: number, dstOffset?: number, size?: number): void;
+    drawIndirect(pass: GPURenderPassEncoder, offset?: number): void;
+    dispatchIndirect(pass: GPUComputePassEncoder, offset?: number): void;
+    mapRead(): Promise<ArrayBuffer>;
+    unmap(): void;
+    destroy(): void;
+}
+declare class TypedBuffer<T extends TapezType = TapezType> implements TypedBufferBase {
+    /** The underlying DirtyUniformBuffer (provides typed array views: .f32, .u32, .i32) */
+    readonly raw: DirtyUniformBuffer;
+    /** The tapez type this buffer was created from */
+    readonly type: T;
+    /**
+     * Named field setters. Only available for struct types.
+     * For non-struct buffers this is an empty object.
+     */
+    readonly set: T extends TapezStruct<infer F> ? Setters<F> : Record<string, never>;
+    /**
+     * Named field getters. Only available for struct types.
+     * For non-struct buffers this is an empty object.
+     */
+    readonly get: T extends TapezStruct<infer F> ? Getters<F> : Record<string, never>;
+    private constructor();
+    /** The raw GPUBuffer — for texture/sampler bind group entries only */
+    get buffer(): GPUBuffer;
+    /** Total byte size of the buffer */
+    get byteSize(): number;
+    /** Whether any values have changed since last write */
+    get isDirty(): boolean;
+    /** Force dirty state (for external invalidation) */
+    markDirty(): void;
+    /** Upload to GPU only if dirty, then clear dirty flag */
+    writeIfDirty(queue: GPUQueue): void;
+    /** Upload to GPU unconditionally */
+    write(queue: GPUQueue): void;
+    /**
+     * Bulk set multiple struct fields at once.
+     * Only available for struct-typed buffers.
+     */
+    writeFields(values: Partial<{
+        [K in keyof FieldsOf<T>]: SetterValue<FieldsOf<T>[K]>;
+    }>): void;
+    /** Destroy the underlying GPU buffer */
+    destroy(): void;
+    /** Write raw data to this buffer via queue.writeBuffer */
+    writeRaw(queue: GPUQueue, data: BufferSource | SharedArrayBuffer, bufferOffset?: number, dataOffset?: number, size?: number): void;
+    /** Copy data from this buffer to another TypedBuffer */
+    copyTo(encoder: GPUCommandEncoder, dest: TypedBuffer, srcOffset?: number, dstOffset?: number, size?: number): void;
+    /** Copy data from another TypedBuffer into this buffer */
+    copyFrom(encoder: GPUCommandEncoder, src: TypedBuffer, srcOffset?: number, dstOffset?: number, size?: number): void;
+    /** Use this buffer for drawIndirect */
+    drawIndirect(pass: GPURenderPassEncoder, offset?: number): void;
+    /** Use this buffer for dispatchWorkgroupsIndirect */
+    dispatchIndirect(pass: GPUComputePassEncoder, offset?: number): void;
+    /** Map buffer for reading (for readback buffers). Returns the mapped ArrayBuffer. */
+    mapRead(): Promise<ArrayBuffer>;
+    /** Unmap a previously mapped buffer */
+    unmap(): void;
+    /** Create a buffer with explicit usage flags. Accepts any TapezType. */
+    static create<T extends TapezType>(device: GPUDevice, type: T, label: string, usage: GPUBufferUsageFlags): TypedBuffer<T>;
+    /** Create a uniform buffer (UNIFORM | STORAGE | COPY_DST) */
+    static createUniform<T extends TapezType>(device: GPUDevice, type: T, label: string): TypedBuffer<T>;
+    /** Create a storage buffer (STORAGE | COPY_DST). Pass extraFlags for COPY_SRC etc. */
+    static createStorage<T extends TapezType>(device: GPUDevice, type: T, label: string, extraFlags?: GPUBufferUsageFlags): TypedBuffer<T>;
+    /** Create an indirect draw/dispatch buffer (INDIRECT | STORAGE | COPY_DST) */
+    static createIndirect<T extends TapezType>(device: GPUDevice, type: T, label: string): TypedBuffer<T>;
+    /** Create a readback buffer (MAP_READ | COPY_DST). For GPU→CPU data transfer. */
+    static createReadback<T extends TapezType>(device: GPUDevice, type: T, label: string): TypedBuffer<T>;
+}
+
+/**
+ * Bind group layout/entry helpers for TypedBuffer.
+ *
+ * Reduces boilerplate when creating bind group layouts and bind groups
+ * from typed buffers.
+ *
+ * Usage:
+ *   const layout = device.createBindGroupLayout({
+ *     entries: [
+ *       uniformEntry(0, GPUShaderStage.COMPUTE),
+ *       storageEntry(1, GPUShaderStage.COMPUTE, 'read-only-storage'),
+ *     ]
+ *   })
+ *
+ *   const bindGroup = device.createBindGroup({
+ *     layout,
+ *     entries: [
+ *       bufferEntry(0, configBuf),
+ *       bufferEntry(1, stateBuf),
+ *     ]
+ *   })
+ */
+
+/**
+ * Create a bind group layout entry for a uniform buffer.
+ */
+declare function uniformEntry(binding: number, visibility: GPUShaderStageFlags): GPUBindGroupLayoutEntry;
+/**
+ * Create a bind group layout entry for a storage buffer.
+ */
+declare function storageEntry(binding: number, visibility: GPUShaderStageFlags, type?: 'storage' | 'read-only-storage'): GPUBindGroupLayoutEntry;
+/**
+ * Create a bind group entry from a TypedBuffer or raw GPUBuffer.
  */
-export { f32, u32, i32, atomic } from './types';
-export type { TapezType, TapezScalar, TapezAtomic } from './types';
-export { vec2f, vec3f, vec4f, vec2u, vec3u, vec4u, vec2i, vec3i, vec4i } from './vectors';
-export type { TapezVector } from './vectors';
-export { mat2x2f, mat3x3f, mat4x4f } from './matrix';
-export type { TapezMatrix } from './matrix';
-export { struct } from './struct';
-export type { TapezStruct } from './struct';
-export { arrayOf } from './array';
-export type { TapezArray } from './array';
-export { constant as const } from './const';
-export type { TapezConst } from './const';
-export { TypedBuffer, type TypedBufferBase } from './typed-buffer';
-export { uniformEntry, storageEntry, bufferEntry } from './bind-helpers';
-export { roundUp, computeStructLayout } from './layout';
-export type { FieldLayout, StructLayout } from './layout';
-//# sourceMappingURL=index.d.ts.map
+declare function bufferEntry(binding: number, buf: TypedBufferBase | GPUBuffer): GPUBindGroupEntry;
+
+export { type FieldLayout, type StructLayout, type TapezArray, type TapezAtomic, type TapezConst, type TapezMatrix, type TapezScalar, type TapezStruct, type TapezType, type TapezVector, TypedBuffer, type TypedBufferBase, arrayOf, atomic, bufferEntry, computeStructLayout, constant as const, f32, i32, mat2x2f, mat3x3f, mat4x4f, roundUp, storageEntry, struct, u32, uniformEntry, vec2f, vec2i, vec2u, vec3f, vec3i, vec3u, vec4f, vec4i, vec4u };