wesl-gpu 0.1.9 → 0.1.12

package/dist/index.d.ts

@@ -0,0 +1,185 @@
+import { LinkParams, VirtualLibraryFn } from "wesl";
+
+//#region src/DeviceCache.d.ts
+
+/**
+ * WeakMap cache for GPUDevice-based caching
+ *
+ * GPUDevices are weakly held to avoid memory leaks.
+ */
+declare class DeviceCache<T> {
+  private cache;
+  get(device: GPUDevice, key: string): T | undefined;
+  set(device: GPUDevice, key: string, value: T): void;
+}
+//#endregion
+//#region src/ErrorScopes.d.ts
+/**
+ * Runs a function with WebGPU error scopes, automatically handling push/pop/check.
+ * Throws if any validation, out-of-memory, or internal errors occur.
+ */
+declare function withErrorScopes<T>(device: GPUDevice, fn: () => T | Promise<T>): Promise<T>;
+//#endregion
+//#region src/ExampleTextures.d.ts
+interface SamplerOptions {
+  addressMode?: "clamp-to-edge" | "repeat" | "mirror-repeat";
+  filterMode?: "nearest" | "linear";
+}
+/** Create texture filled with solid color. Internally cached. */
+declare function solidTexture(device: GPUDevice, color: [r: number, g: number, b: number, a: number], width: number, height: number): GPUTexture;
+/** Create gradient texture. Direction: 'horizontal' (default) or 'vertical'. */
+declare function gradientTexture(device: GPUDevice, width: number, height: number, direction?: "horizontal" | "vertical"): GPUTexture;
+/** Create checkerboard pattern. cellSize: pixels per cell (default: width/4). */
+declare function checkerboardTexture(device: GPUDevice, width: number, height: number, cellSize?: number): GPUTexture;
+/** Create sampler. Default: linear filtering with clamp-to-edge. Internally cached. */
+declare function createSampler(device: GPUDevice, options?: SamplerOptions): GPUSampler;
+/** Create radial gradient texture (white center to black edge). */
+declare function radialGradientTexture(device: GPUDevice, size: number): GPUTexture;
+/** Create edge pattern texture with sharp vertical, horizontal, and diagonal lines. */
+declare function edgePatternTexture(device: GPUDevice, size: number): GPUTexture;
+/** Create color bars texture (RGB primaries and secondaries). */
+declare function colorBarsTexture(device: GPUDevice, size: number): GPUTexture;
+/** Create seeded noise pattern (deterministic). */
+declare function noiseTexture(device: GPUDevice, size: number, seed?: number): GPUTexture;
+//#endregion
+//#region src/RenderUniforms.d.ts
+/** User provided uniform values */
+interface RenderUniforms {
+  /** Elapsed time in seconds (default: 0.0) */
+  time?: number;
+  /** Mouse position in [0,1] normalized coords (default: [0.0, 0.0]) */
+  mouse?: [number, number];
+}
+/**
+ * Creates a standard uniform buffer for running test fragment shaders.
+ *
+ * @param outputSize - Output texture dimensions (becomes uniforms.resolution)
+ * @param uniforms - User-provided uniform values (time, mouse)
+ * @returns GPUBuffer containing uniform data
+ */
+declare function renderUniformBuffer(device: GPUDevice, outputSize: [number, number], uniforms?: RenderUniforms): GPUBuffer;
+/**
+ * Updates an existing uniform buffer with new values.
+ * Use this for per-frame updates in render loops (avoids buffer recreation).
+ *
+ * @param buffer - Existing uniform buffer to update
+ * @param device - GPU device
+ * @param resolution - Output texture dimensions
+ * @param time - Elapsed time in seconds
+ * @param mouse - Mouse position [0,1] normalized coords
+ */
+declare function updateRenderUniforms(buffer: GPUBuffer, device: GPUDevice, resolution: [number, number], time: number, mouse?: [number, number]): void;
+/**
+ * return the WGSL struct for use in shaders as test::Uniforms.
+ *
+ * @returns virtual library object for passing to compileShader()
+ */
+declare function createUniformsVirtualLib(): Record<string, VirtualLibraryFn>;
+//#endregion
+//#region src/FragmentParams.d.ts
+/** WESL linker options - aligned with wesl's LinkParams */
+type WeslOptions = Pick<LinkParams, "resolver" | "weslSrc" | "rootModuleName" | "conditions" | "libs" | "virtualLibs" | "packageName" | "constants" | "config">;
+/** GPU rendering params for fragment shaders */
+interface FragmentRenderParams {
+  device: GPUDevice;
+  /** Output texture format. Default: "rgba32float" */
+  textureFormat?: GPUTextureFormat;
+  /** Output texture size. Default: [1, 1] */
+  size?: [width: number, height: number];
+  /** Uniform values (time, mouse). Resolution auto-populated from size. */
+  uniforms?: RenderUniforms;
+  /** Input textures. Bindings: [1..n], samplers at [n+1..n+m]. */
+  textures?: GPUTexture[];
+  /** Samplers. Length 1 (reused) or match textures.length. */
+  samplers?: GPUSampler[];
+}
+/** Combined params for fragment shader execution */
+interface FragmentParams extends WeslOptions, FragmentRenderParams {
+  /** Fragment shader source (vertex shader auto-provided) */
+  src: string;
+}
+//#endregion
+//#region src/FragmentPipeline.d.ts
+type LinkFragmentParams = WeslOptions & {
+  device: GPUDevice;
+  /** Fragment shader source (vertex shader is auto-provided) */
+  fragmentSource: string;
+};
+interface LinkAndCreateParams extends LinkFragmentParams {
+  format: GPUTextureFormat;
+  layout?: GPUPipelineLayout | "auto";
+}
+/** Combined: link WESL source and create pipeline in one step. */
+declare function linkAndCreatePipeline(params: LinkAndCreateParams): Promise<GPURenderPipeline>;
+/**
+ * Link a WESL/WGSL fragment shader to a shader module.
+ * Adds:
+ * - vertex shader that covers the viewport with a fullscreen triangle
+ * - a virtual module containing a std uniform buffer (for size, etc.)
+ */
+declare function linkFragmentShader(params: LinkFragmentParams): Promise<GPUShaderModule>;
+//#endregion
+//#region src/FragmentRender.d.ts
+interface RenderFrameParams {
+  device: GPUDevice;
+  pipeline: GPURenderPipeline;
+  bindGroup?: GPUBindGroup;
+  targetView: GPUTextureView;
+}
+/** Execute one fullscreen fragment render pass to target view. */
+declare function renderFrame(params: RenderFrameParams): void;
+//#endregion
+//#region src/FullscreenVertex.d.ts
+/** Number of vertices drawn for fullscreen quad using triangle-strip topology */
+declare const fullscreenVertexCount = 4;
+/** Fullscreen triangle vertex shader that covers viewport with 3 vertices, no vertex buffer needed */
+declare const fullscreenTriangleVertex = "\n  @vertex\n  fn vs_main(@builtin(vertex_index) idx: u32) -> @builtin(position) vec4f {\n    // Covers viewport with 3 vertices, no vertex buffer needed\n    var pos: vec2f;\n    if (idx == 0u) {\n      pos = vec2f(-1.0, -1.0);\n    } else if (idx == 1u) {\n      pos = vec2f(3.0, -1.0);\n    } else {\n      pos = vec2f(-1.0, 3.0);\n    }\n    return vec4f(pos, 0.0, 1.0);\n  }";
+//#endregion
+//#region src/RunFragment.d.ts
+/**
+ * Run a fragment shader and return pixel data.
+ *
+ * Combines linking, uniform setup, and rendering into a single call.
+ * Useful for shader testing or single-frame renders.
+ *
+ * @returns Pixel data as a flattened number array
+ */
+declare function runFragment(params: FragmentParams): Promise<number[]>;
+//#endregion
+//#region src/SimpleRender.d.ts
+interface SimpleRenderParams {
+  device: GPUDevice;
+  /** shader module to run, presumed to have one vertex and one fragment entry */
+  module: GPUShaderModule;
+  /** format of the output texture. default "rgba32float" */
+  outputFormat?: GPUTextureFormat;
+  /** size of the output texture. default [1, 1]
+   * Use [2, 2] for derivative tests
+   * Use [512, 512] for visual image tests */
+  size?: [number, number];
+  /** Input textures to bind in group 0.
+   * Bindings: textures at [1..n], samplers at [n+1..n+m]. */
+  textures?: GPUTexture[];
+  /** Samplers for the input textures.
+   * Must be length 1 (reused for all textures) or match textures.length exactly. */
+  samplers?: GPUSampler[];
+  /** pass these uniforms to the shader in group 0 binding 0 */
+  uniformBuffer?: GPUBuffer;
+}
+/**
+ * Executes a render pipeline with the given shader module.
+ * Creates a texture with the specified format, renders to it, and returns all pixel data.
+ * @returns output texture contents in a flattened array (rows flattened, color channels interleaved).
+ */
+declare function simpleRender(params: SimpleRenderParams): Promise<number[]>;
+/**
+ * Create bind group with optional uniforms, textures, and samplers.
+ * Binding layout: 0=uniform buffer (if provided), 1..n=textures, n+1..n+m=samplers.
+ * Samplers must be length 1 (reused for all textures) or match textures.length exactly.
+ */
+declare function createBindGroup(device: GPUDevice, uniformBuffer: GPUBuffer | undefined, textures?: GPUTexture[], samplers?: GPUSampler[]): {
+  layout: GPUBindGroupLayout;
+  bindGroup: GPUBindGroup;
+};
+//#endregion
+export { DeviceCache, FragmentParams, FragmentRenderParams, LinkAndCreateParams, LinkFragmentParams, RenderFrameParams, RenderUniforms, SamplerOptions, SimpleRenderParams, WeslOptions, checkerboardTexture, colorBarsTexture, createBindGroup, createSampler, createUniformsVirtualLib, edgePatternTexture, fullscreenTriangleVertex, fullscreenVertexCount, gradientTexture, linkAndCreatePipeline, linkFragmentShader, noiseTexture, radialGradientTexture, renderFrame, renderUniformBuffer, runFragment, simpleRender, solidTexture, updateRenderUniforms, withErrorScopes };

package/package.json

@@ -1,18 +1,22 @@
 {
   "name": "wesl-gpu",
   "description": "Browser-compatible WebGPU utilities for shader testing and rendering",
-  "version": "0.1.9",
+  "version": "0.1.12",
   "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
   "repository": "github:wgsl-tooling-wg/wesl-js",
   "exports": {
     ".": {
-      "types": "./dist/index.d.mts",
-      "import": "./dist/index.mjs"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
   "dependencies": {
     "thimbleberry": "^0.2.10",
-    "wesl": "0.7.6"
+    "wesl": "0.7.9"
   },
   "devDependencies": {
     "@webgpu/types": "^0.1.68"
@@ -32,5 +36,5 @@
     "test:once": "vitest run",
     "typecheck": "tsgo"
   },
-  "main": "./dist/index.mjs"
+  "main": "./dist/index.js"
 }

package/tsconfig.json

@@ -1,3 +0,0 @@
-{
-  "extends": "../../tsconfig.browser.json"
-}