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**:

```js
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:

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

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

```bash
npm install webgpu-framework
```

```js
import Shader from "webgpu-framework";
```

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

---

## Quick Example — Compute Shader

```js
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

```js
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:

```js
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](https://kajdijkstra.com)
Email: [kajdijkstra@protonmail.com](mailto: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.