WebGpu-Wasm-Raytracing-And-Particles/README.md

# 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