Initial commit

README.md

@@ -1,3 +1,230 @@
-# WebGPU-Framework
+Here is a full **professional** README for your WebGPU Framework — polished, structured, and hire-worthy.
 
-High-level GPU Compute + Rendering for Browser & Node.js.
+If you want, I can also produce a shorter “NPM package style” version or include diagrams/screenshots.
+
+---
+
+# 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.