244 lines
5.5 KiB
Markdown
244 lines
5.5 KiB
Markdown
# 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 demos
|
||
|
||
node server.js
|
||
|
||
then browse to localhost:3030/demos/
|
||
|
||
#### Nodejs demo
|
||
|
||
first install. in this project root.
|
||
|
||
|
||
```html
|
||
npm i
|
||
```
|
||
|
||
To start the demo:
|
||
|
||
Open the directory
|
||
|
||
```command
|
||
cd ./demos/NodeJS
|
||
```
|
||
|
||
then execute:
|
||
|
||
```command
|
||
node index.js
|
||
```
|
||
|
||
|
||
#### How to use the code
|
||
|
||
|
||
|
||
Browser:
|
||
|
||
```html
|
||
<script type="module" src="./framework/WebGpu.js"></script>
|
||
```
|
||
|
||
Node.js (requires headless or windowed WebGPU runtime):
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
```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)
|
||
|