WebGPU-Framework/README.md

WebGPU Framework

High-level GPU Compute + Rendering for Browser & Node.js Write once — run on WebGPU everywhere.

WebGPU exposes massive GPU power — but also a very low-level API full of pipelines, descriptor layouts, bind groups, command buffers, and sync issues.

This framework brings clarity and simplicity:

const shader = new Shader(device);

await shader.setup("path/to/shader.wgsl");

shader.setVariable("gravity", -2.3);
shader.setBuffer("positions", buffer);

await shader.execute(numWorkgroups);

No boilerplate. No bind group confusion. Just GPU work.

---

✨ Key Features

Feature	Description
Unified API	Same code works in browser or native Node.js GPU contexts
Shader-first design	Bind uniforms & buffers by name — the framework auto-builds pipelines
Automatic bind group management	No descriptor juggling
Compute & Rendering	Full support for GPU compute pipelines & mesh rendering
Camera, Matrix & Vector math utilities	Real 3D scenes ready to go
Event system (browser & desktop)	Camera & input control mapped seamlessly
Debug utilities	Inspect GPU buffers during runtime
Fast iteration	Live shader reload (optional extension)

---

Getting Started

Installation

Browser:

<script type="module" src="./framework/WebGpu.js"></script>

Node.js (requires headless or windowed WebGPU runtime):

npm install webgpu-framework

import Shader from "webgpu-framework";

Rendering works in Node using a native window — same code as browser.

---

Quick Example — Compute Shader

const device = await navigator.gpu.requestDevice();
const shader = new Shader(device);

await shader.setup("./shaders/addVectors.wgsl");

shader.setBuffer("inputA", bufferA);
shader.setBuffer("inputB", bufferB);
shader.setBuffer("output", bufferOut);

await shader.execute(256);

---

Quick Example — Rendering Particles

const shader = new Shader(device, "./shaders/points.wgsl");

shader.setCanvas(canvas);
shader.setBuffer("positions", particleBuffer);

shader.renderToCanvas(
    vertexCount = particleCount,
    instanceCount = 1
);

That’s all you need.

---

Example Project Included: 3D Particle Simulation

• 16K moving particles
• Gravity, spatial hashing, collision detection
• Bitonic GPU sorting
• Full compute → render → compute loop

Demo code:

import { ParticleSimulation } from "./demo/ParticleSimulation.js";

const sim = new ParticleSimulation();
await sim.setup(canvas, 1280, 720);
sim.render();

---

Under the Hood

This framework builds and manages:

• GPUDevice, SwapChain, Render Passes
• Pipeline creation (compute + render)
• Bind groups and layouts
• Buffer creation + dynamic sized uniform arrays
• Command submission + synchronization

The developer writes:

• WGSL shaders
• Minimal JavaScript to bind variables

All complexity stays internal.

---

Architecture

Your Code
   |
   | setVariable(), setBuffer(), execute(), render()
   v
WebGPU Framework
   |
   | Auto-bind pipelines, sync, command buffers
   v
Native WebGPU (Browser or Node.js)
   |
   v
GPU

---

API Summary

Method	Purpose
setup(path)	Load & compile a WGSL shader
setVariable(name, value)	Upload uniform values (numbers, vectors, matrices…)
setBuffer(name, gpuBuffer)	Bind device buffers by name
execute(workgroups)	Dispatch compute workloads
renderToCanvas(verts, instances)	Draw geometry to output surface
debugBuffer(name)	Inspect GPU buffer contents

Camera/Math/Event utilities:

• Matrix4, Vector3, Camera
• EventManager for mouse/touch/keyboard (browser + Node)

---

Requirements

• Modern GPU with WebGPU support
• Browser support: Chromium-based + Firefox Nightly
• Node.js support: wgpu-native or compatible environments

---

Status

Component	State
Core Shader API	✓ Stable
Browser rendering	✓ Fully working
Node.js rendering	✓ Fully working
Advanced pipelines	🚧 In progress
Cross-platform demos	🚧 More coming

---

License

MIT License © 2025 Kaj Dijkstra

---

Author

Kaj Dijkstra Leeuwarden, Netherlands Portfolio: https://kajdijkstra.com Email: kajdijkstra@protonmail.com

---

Would you like me to:

✔ Add diagrams illustrating compute → sort → grid hashing pipeline ✔ Add screenshots from your particle simulation ✔ Add performance benchmarks ✔ Add a “Why use this instead of raw WebGPU?” section ✔ Publish this to npm with clean package layout

Also — should we link this repo from your CV under Projects with a short bullet like:

High-level WebGPU framework enabling real-time GPU compute + rendering in browser and native runtimes with a minimal API

If you're ready, I can push this README into your Gitea repository automatically.