From 775f848f615aeafae6f255ea1f66da9df2f6ceb8 Mon Sep 17 00:00:00 2001
From: kaj dijkstra <kajdijkstra@protonmail.com>
Date: Tue, 30 Dec 2025 20:49:41 +0100
Subject: [PATCH] Readme

---
 README.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 146 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..805d9d3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,146 @@
+
+# WebGPU + WebAssembly Demos
+
+This repository contains multiple experimental demos combining **WebGPU rendering** with **WebAssembly computation**, focused on high-performance graphics and data-parallel workloads in the browser.
+
+The demos are served locally via a small Node.js HTTPS server and require a browser with WebGPU enabled.
+
+---
+
+## Overview
+
+Each demo follows the same high-level architecture:
+
+* **Computation** is performed in WebAssembly (optionally with pthreads)
+* **Rendering** is performed using WebGPU
+* **Data exchange** happens via shared linear memory (WASM → JavaScript → GPU buffers)
+
+One example demo is a **particle simulation** where particle positions and attributes are updated in WebAssembly and rendered each frame using instanced point-sprite quads in WebGPU.
+
+---
+
+## Particle Simulation Demo
+
+### Architecture
+
+* Particle state lives entirely in WASM linear memory
+* JavaScript maps the WASM memory into a `Float32Array`
+* Each frame:
+
+  1. WASM updates particle positions (`_update_particles`)
+  2. The particle buffer is uploaded to a WebGPU storage buffer
+  3. A WebGPU render pass draws particles using a WGSL shader
+
+### Key Technologies
+
+* WebGPU (rendering)
+* WebAssembly (simulation)
+* SharedArrayBuffer (when pthreads are enabled)
+* Custom minimal WebGPU framework
+* WGSL shaders
+
+---
+
+## Repository Structure
+
+```
+.
+├── demos/
+│   ├── WebGpuFrameworkWasm/
+│   ├── webGpuFrameworkAndWasmParticles/
+│   └── webGpuNativeWasm/
+│
+├── framework/
+│   ├── WebGpu.js
+│   ├── Camera.js
+│   ├── Matrix4.js
+│   ├── Vector3.js
+│   └── EventManager.js
+│
+├── shaders/
+│   ├── simplePoint.wgsl
+│   └── taa.wgsl
+│
+├── textures/
+│
+├── wasm_add_pthread.js
+├── wasm_add_pthread.wasm
+│
+├── server.js
+├── package.json
+│
+├── localhost.pem
+├── localhost-key.pem
+```
+
+---
+
+## Requirements
+
+* Chromium-based browser with WebGPU enabled
+  (Chrome, Chromium, or Edge with `--enable-unsafe-webgpu`)
+* Node.js (for the local HTTPS server)
+* HTTPS is required for:
+
+  * WebGPU
+  * SharedArrayBuffer
+  * WebAssembly pthreads
+
+---
+
+## Installation
+
+Install dependencies:
+
+```
+npm install
+```
+
+---
+
+## Running the Demos
+
+Start the local HTTPS server:
+
+```
+node server.js
+```
+
+Open your browser at:
+
+```
+https://localhost:PORT
+```
+
+(The exact port is printed by `server.js`.)
+
+Navigate to one of the demo directories under `/demos`.
+
+---
+
+## Notes on WASM + WebGPU Integration
+
+* Particle buffers are **not copied per particle**; a single contiguous buffer is shared.
+* The WASM module exposes:
+
+  * particle count
+  * particle pointer
+  * update function
+* JavaScript performs a direct `writeBuffer` call each frame using the mapped WASM memory.
+* Rendering uses instanced quads (6 vertices per particle).
+
+---
+
+## Status
+
+This repository is experimental and intended for research and prototyping purposes:
+
+* APIs may change
+* No stability guarantees
+* No abstraction layer beyond what is needed for experimentation
+
+---
+
+## License
+
+MIT