@plasius/gpu-worker 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -20,6 +20,51 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 - **Security**
   - (placeholder)
 
+## [0.1.2] - 2026-01-24
+
+- **Added**
+  - `loadJobWgsl` to register multiple job WGSL modules and receive `job_type` ids.
+  - Job-aware `assembleWorkerWgsl` that appends registered jobs and generates a dispatch wrapper.
+  - Optional debug mode for WGSL identifier clash detection during assembly.
+  - `loadQueueWgsl` helper that can apply queue compatibility renames during load.
+  - `createWorkerLoop` helper to drive worker/job compute dispatch at max or throttled rates.
+  - Demo denoise job WGSL (`demo/jobs/denoise.wgsl`) with a compute pass + present shader.
+  - Temporal denoise history buffer in the demo to stabilize jittered lighting.
+
+- **Changed**
+  - Demo visuals now render a campfire scene with deferred lighting (G-buffer + fullscreen lighting pass).
+  - Demo now builds per-type worklists from queue jobs and uses indirect draws for render jobs alongside physics jobs.
+  - `src/worker.wgsl` is now a minimal worker template; demo kernels live in `demo/jobs/*.wgsl`.
+  - Demo job shaders are split into `demo/jobs/common.wgsl`, `demo/jobs/physics.job.wgsl`, and `demo/jobs/render.job.wgsl`.
+  - Demo lighting sampling now uses screen-space jitter to avoid world-space banding artifacts.
+  - `assembleWorkerWgsl` can now consume a registry or explicit job list and emit a dispatching `process_job`.
+  - `assembleWorkerWgsl` now applies queue compatibility renames (e.g., `JobMeta` -> `JobDesc`) by default.
+
+- **Fixed**
+  - Reduced diagonal banding artifacts in the demo lighting pass.
+
+- **Security**
+  - (placeholder)
+
+## [0.1.1] - 2026-01-23
+
+- **Added**
+  - `assembleWorkerWgsl` now accepts optional queue WGSL overrides for local demos.
+
+- **Changed**
+  - Demo now simulates millions of instanced objects with range checks, bounding spheres/AABBs, and face contact stats.
+  - **Breaking:** Queue bindings updated to remove the payload arena and use payload offsets into caller-managed buffers.
+  - Demo updated to match the new payload-handle layout.
+  - **Breaking:** Queue bindings now use job metadata and a variable-size payload arena.
+  - Worker job payloads are read from the output payload buffer using `output_stride`.
+  - Demo updated to emit job metadata and payload buffers.
+
+- **Fixed**
+  - Demo can load a local queue WGSL to avoid mismatched dependency versions.
+
+- **Security**
+  - (placeholder)
+
 ## [0.1.0] - 2026-01-22
 
 - **Added**
@@ -69,6 +114,7 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 
 ---
 
-[Unreleased]: https://github.com/Plasius-LTD/gpu-worker/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/Plasius-LTD/gpu-worker/compare/v0.1.2...HEAD
 [0.1.0-beta.1]: https://github.com/Plasius-LTD/gpu-worker/releases/tag/v0.1.0-beta.1
 [0.1.0]: https://github.com/Plasius-LTD/gpu-worker/releases/tag/v0.1.0
+[0.1.2]: https://github.com/Plasius-LTD/gpu-worker/releases/tag/v0.1.2

package/README.md

@@ -15,38 +15,115 @@ npm install @plasius/gpu-worker
 
 ## Usage
 ```js
-import { assembleWorkerWgsl, loadWorkerWgsl } from "@plasius/gpu-worker";
+import {
+  assembleWorkerWgsl,
+  createWorkerLoop,
+  loadJobWgsl,
+  loadWorkerWgsl,
+} from "@plasius/gpu-worker";
 
 const workerWgsl = await loadWorkerWgsl();
-const shaderCode = await assembleWorkerWgsl(workerWgsl);
+const jobType = await loadJobWgsl({
+  wgsl: `
+fn process_job(job_index: u32, job_type: u32, payload_words: u32) {
+  // job logic here
+}
+`,
+  label: "physics",
+});
+
+const shaderCode = await assembleWorkerWgsl(workerWgsl, { debug: true });
 // Pass shaderCode to device.createShaderModule({ code: shaderCode })
 ```
 
+`loadJobWgsl` registers job WGSL and returns the assigned `job_type` index.
+Call `assembleWorkerWgsl` again after registering new jobs to rebuild the
+combined WGSL. Job types are assigned in registration order, so keep the
+registration order stable across rebuilds if you need deterministic ids.
+
+`assembleWorkerWgsl` also accepts an optional second argument to override the
+queue WGSL source: `assembleWorkerWgsl(workerWgsl, { queueWgsl, queueUrl, fetcher })`.
+By default it applies queue compatibility renames (for example `JobMeta` -> `JobDesc`);
+set `queueCompat: false` to disable that behavior.
+If you are concatenating WGSL manually, `loadQueueWgsl` provides the same
+compatibility renames by default: `loadQueueWgsl({ url, fetcher, queueCompat: false })`.
+
+To bypass the registry, pass jobs directly:
+```js
+const shaderCode = await assembleWorkerWgsl(workerWgsl, {
+  jobs: [{ wgsl: jobA }, { wgsl: jobB, label: "lighting" }],
+  debug: true,
+});
+```
+
+When assembling jobs, each job WGSL must define
+`process_job(job_index, job_type, payload_words)`. The assembler rewrites each
+job's `process_job` to a unique name and generates a dispatcher based on
+`job_type`. Set `debug: true` to detect identifier clashes across appended WGSL.
+
+To run the worker loop at the highest practical rate (or a target rate), use the
+helper:
+```js
+const loop = createWorkerLoop({
+  device,
+  worker: { pipeline: workerPipeline, bindGroups: [queueBindGroup, simBindGroup] },
+  jobs: [
+    { pipeline: physicsPipeline, bindGroups: [queueBindGroup, simBindGroup], workgroups: physicsWorkgroups },
+    { pipeline: renderIndirectPipeline, bindGroups: [queueBindGroup, simBindGroup], workgroups: 1 },
+  ],
+  workgroupSize: 64,
+  maxJobsPerDispatch: queueCapacity,
+  // rateHz: 120, // optional throttle; omit for animation-frame cadence
+});
+loop.start();
+```
+
 ## What this is
 - A minimal GPU worker layer that combines a lock-free queue with user WGSL jobs.
 - A helper to assemble WGSL modules with queue helpers included.
 - A reference job format for fixed-size job dispatch (u32 indices).
 
 ## Demo
-The demo enqueues ray tracing tile jobs on the GPU and renders a simple scene. Install
-dependencies first so the lock-free queue package is available for the browser import map.
+The demo enqueues physics and render jobs on the GPU, builds per-type worklists, runs the
+physics kernel, and uses an indirect draw for the particle pass. Install dependencies first
+so the lock-free queue package is available for the browser import map.
 
 ```
 npm install
-python3 -m http.server
+npm run demo
 ```
 
 Then open `http://localhost:8000/demo/`.
 
+### HTTPS demo
+WebGPU requires a secure context. For non-localhost access, run the HTTPS demo server.
+
+```
+mkdir -p demo/certs
+mkcert -key-file demo/certs/localhost-key.pem -cert-file demo/certs/localhost.pem localhost 127.0.0.1 ::1
+# or
+openssl req -x509 -newkey rsa:2048 -nodes -keyout demo/certs/localhost-key.pem -out demo/certs/localhost.pem -days 365 -subj "/CN=localhost" -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
+npm run demo:https
+```
+
+Then open `https://localhost:8443/demo/`. If you use a different hostname/IP, generate a
+certificate for that name and set `DEMO_HOST`, `DEMO_PORT`, `DEMO_TLS_CERT`, and
+`DEMO_TLS_KEY` as needed.
+
 ## Build Outputs
 
 `npm run build` emits `dist/index.js`, `dist/index.cjs`, and `dist/worker.wgsl`.
 
 ## Files
-- `demo/index.html`: Loads the ray tracing demo.
-- `demo/main.js`: WebGPU setup, enqueue, and ray tracing kernel.
-- `src/worker.wgsl`: Worker entry points that dequeue jobs and run a ray tracer.
+- `demo/index.html`: Loads the WebGPU demo.
+- `demo/main.js`: WebGPU setup, queue jobs, physics worklists, and indirect draw.
+- `demo/jobs/common.wgsl`: Shared WGSL definitions for demo jobs.
+- `demo/jobs/physics.job.wgsl`: Physics job kernel (worklist + integration).
+- `demo/jobs/render.job.wgsl`: Render job kernel (worklist + indirect args).
+- `src/worker.wgsl`: Minimal worker entry point template (dequeue + `process_job` hook).
 - `src/index.js`: Helper functions to load/assemble WGSL.
 
 ## Job shape
-Jobs are `u32` indices into a fixed workload array (tiles, particles, etc). Keep job data fixed-size; use indices into a separate payload buffer for variable payloads.
+Jobs are variable-length payloads stored in a caller-managed buffer. Each job supplies `job_type`, `payload_offset`, and `payload_words` metadata plus a payload stored in the input payload buffer. For simple cases, use a single-word payload containing an index into your workload array.
+
+Set `output_stride` in queue params to the maximum payload size you want copied out for a job; `job_type` can be used by schedulers to route work to different kernels. The queue mirrors input metadata into `output_jobs` and optionally copies payloads into `output_payloads`.