typegpu-shader-canvas 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Wayne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# typegpu-shader-canvas
+
+This library makes it easy to render TypeScript based fragment shaders directly to a web based canvas element. This is made possible by the amazing [TypeGPU](https://typegpu.com) library.
+
+- 🚫 No setting up a WebGPU device or pipeline
+- 🚫 No need to render triangle geometry
+- 🚫 No need to write vertex shaders
+- ✨ Just provide a canvas, and your shader code, and look at the pretty pixels.
+
+
+## Features
+
+- 🖱️ Mouse event handling for both position and clicked buttons, including off canvas tracking.
+- 📐 Use `uv` (clip space) or `xy` (pixels) based coordinates.
+- 🔄 Automatically start animating in a render loop.
+
+
+## Installation
+
+```bash
+npm install typegpu-shader-canvas
+```
+
+### WebGPU Types
+
+Your `tsconfig.json` **must** include [`@webgpu/types`](https://docs.swmansion.com/TypeGPU/getting-started/) so TypeScript recognizes WebGPU globals:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@webgpu/types"]
+  }
+}
+```
+
+### Build Plugin
+
+Your build pipeline **must** include [`unplugin-typegpu`](https://docs.swmansion.com/TypeGPU/tooling/unplugin-typegpu/) — This is what allows your shader to be compiled to WebGPU's WGSL.
+
+
+#### Vite example
+
+```ts
+// vite.config.ts
+import typegpuPlugin from 'unplugin-typegpu/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [typegpuPlugin({})],
+})
+```
+
+## Usage
+
+```ts
+import { vec3f, vec4f } from 'typegpu/data'
+import { mix, sin } from 'typegpu/std'
+import { createShaderCanvas } from 'typegpu-shader-canvas'
+
+createShaderCanvas(
+  document.getElementById('canvas'),
+  ({ uv, time }) => {
+    'use gpu'
+
+    const color = mix(
+      vec3f(1, 0, 0),
+      vec3f(0, 0, 1),
+      sin(time + uv.x) * 0.5 + 0.5
+    )
+    return vec4f(color, 1)
+  },
+).startRendering()
+```
+
+## API
+
+### `createShaderCanvas(canvas, fragmentShader)`
+
+Creates a WebGPU shader canvas that renders a fragment shader to the given `<canvas>` element.
+
+**Parameters:**
+
+- `canvas` — an `HTMLCanvasElement` (e.g. from `document.getElementById`)
+- `fragmentShader` — a function that receives `FragmentParameters` and returns a `vec4f` color. Must contain a `'use gpu'` directive.
+
+**Returns** an object with:
+
+- `startRendering()` — start a rendering loop with `requestAnimationFrame`.
+- `render()` — renders a single frame. Use this if you want implement you own rendering trigger.
+
+### `FragmentParameters`
+
+The struct passed to your fragment shader function, with these fields:
+
+| Field         | Type    | Description                                  |
+| ------------- | ------- | -------------------------------------------- |
+| `uv`          | `vec2f` | Clip-space coordinates (-1 to 1)             |
+| `xy`          | `vec2f` | Pixel coordinates                            |
+| `time`        | `f32`   | Elapsed time in seconds since page load      |
+| `mouse`       | `Mouse` | Mouse state (see below)                      |
+| `resolution`  | `vec2f` | Canvas resolution in pixels                  |
+| `aspectRatio` | `f32`   | Canvas aspect ratio (width / height)         |
+
+#### `Mouse`
+
+| Field    | Type    | Description                                |
+| -------- | ------- | ------------------------------------------ |
+| `xy`     | `vec2f` | Position in pixels on the canvas           |
+| `uv`     | `vec2f` | Position in clip-space (-1 to 1)           |
+| `isOver` | `i32`   | 1 if the mouse is over the canvas, else 0  |
+| `down`   | `i32`   | 1 if the left mouse button is down, else 0 |

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "typegpu-shader-canvas",
+  "version": "0.1.0",
+  "description": "A simple WebGPU shader canvas powered by TypeGPU",
+  "license": "MIT",
+  "author": "Alex Wayne",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@webgpu/types": "^0.1.69",
+    "typegpu": "^0.9.0",
+    "unplugin-typegpu": "^0.9.0"
+  },
+  "devDependencies": {
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@webgpu/types": "^0.1.69",
+    "prettier": "^3.8.1",
+    "typegpu": "^0.9.0",
+    "typescript": "^5.9.3",
+    "unplugin-typegpu": "^0.9.0",
+    "vite": "^7.3.1"
+  }
+}

package/src/fragment-shader.ts

@@ -0,0 +1,39 @@
+import tgpu, { type TgpuBufferReadonly } from 'typegpu'
+import { type Infer, struct, type v4f, vec2f, vec4f } from 'typegpu/data'
+
+import { ProvidedUniforms } from './provided-uniforms'
+
+export const FragmentParameters = struct({
+  uv: vec2f,
+  xy: vec2f,
+  ...ProvidedUniforms.propTypes,
+})
+export type FragmentParameters = Infer<typeof FragmentParameters>
+
+export function createFragmentShader(
+  fragmentShaderImplementation: (
+    fragmentParameters: Infer<typeof FragmentParameters>,
+  ) => v4f,
+  providedUniforms: TgpuBufferReadonly<typeof ProvidedUniforms>,
+) {
+  return tgpu['~unstable'].fragmentFn({
+    in: { uv: vec2f },
+    out: { color: vec4f },
+  })(({ uv }) => {
+    // Calculate pixel coordinates from clip space coordinates
+    const xy = uv.add(vec2f(1, 1)).mul(providedUniforms.$.resolution).mul(0.5)
+
+    return {
+      color: fragmentShaderImplementation(
+        FragmentParameters({
+          uv,
+          xy,
+          time: providedUniforms.$.time,
+          mouse: providedUniforms.$.mouse,
+          resolution: providedUniforms.$.resolution,
+          aspectRatio: providedUniforms.$.aspectRatio,
+        }),
+      ),
+    }
+  })
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { createShaderCanvas } from './typegpu-shader-canvas'

package/src/mouse.ts

@@ -0,0 +1,45 @@
+import type { TgpuBuffer } from 'typegpu'
+import { type v2f, vec2f } from 'typegpu/data'
+
+import { Mouse, ProvidedUniforms } from './provided-uniforms'
+
+function getXY(event: MouseEvent, rect: DOMRect): v2f {
+  return vec2f(event.clientX - rect.left, -(event.clientY - rect.top))
+}
+
+function getUV(rect: DOMRect, xy: v2f): v2f {
+  return xy.div(vec2f(rect.width, rect.height)).mul(2).sub(vec2f(1, -1))
+}
+
+function getIsOver(rect: DOMRect, xy: v2f): 0 | 1 {
+  const inX = xy.x >= 0 && xy.x <= rect.width
+  const inY = xy.y <= 0 && xy.y >= -rect.height
+  return inX && inY ? 1 : 0
+}
+
+function getMouseDown(event: MouseEvent): 0 | 1 {
+  return (event.buttons & 1) !== 0 ? 1 : 0
+}
+
+export function trackMouse(
+  canvas: HTMLElement,
+  providedUniforms: TgpuBuffer<typeof ProvidedUniforms>,
+): void {
+  function handleMouseEvent(event: MouseEvent) {
+    const rect = canvas.getBoundingClientRect()
+    const xy = getXY(event, rect)
+
+    providedUniforms.writePartial({
+      mouse: Mouse({
+        xy,
+        uv: getUV(rect, xy),
+        isOver: getIsOver(rect, xy),
+        down: getMouseDown(event),
+      }),
+    })
+  }
+
+  document.addEventListener('mousemove', handleMouseEvent)
+  canvas.addEventListener('mousedown', handleMouseEvent)
+  canvas.addEventListener('mouseup', handleMouseEvent)
+}

package/src/provided-uniforms.ts

@@ -0,0 +1,31 @@
+import { type Infer, f32, i32, struct, vec2f } from 'typegpu/data'
+
+export const Mouse = struct({
+  /** The XY position in pixels on the canvas */
+  xy: vec2f,
+
+  /** The UV position on the canvas */
+  uv: vec2f,
+
+  /** 1 if the mouse is over the canvas, 0 otherwise */
+  isOver: i32,
+
+  /** 1 if the left mouse button is down, 0 otherwise */
+  down: i32,
+})
+
+export const ProvidedUniforms = struct({
+  /** Elapsed time since page load, in seconds */
+  time: f32,
+
+  /** The mouse state */
+  mouse: Mouse,
+
+  /** The resolution of the canvas, in pixels */
+  resolution: vec2f,
+
+  /** The aspect ratio of the canvas */
+  aspectRatio: f32,
+})
+
+export type ProvidedUniforms = Infer<typeof ProvidedUniforms>

package/src/typegpu-shader-canvas.ts

@@ -0,0 +1,115 @@
+import tgpu, { type TgpuBufferReadonly } from 'typegpu'
+import { type Infer, type v4f, vec2f } from 'typegpu/data'
+
+import { FragmentParameters, createFragmentShader } from './fragment-shader'
+import { trackMouse } from './mouse'
+import { ProvidedUniforms } from './provided-uniforms'
+import { createVertexShader, quadVertices } from './vertex-shader'
+
+const root = await tgpu.init()
+const presentationFormat = navigator.gpu.getPreferredCanvasFormat()
+
+export function createShaderCanvas(
+  canvas: HTMLElement | undefined | null,
+  fragmentShaderImplementation: (
+    fragmentParameters: Infer<typeof FragmentParameters>,
+  ) => v4f,
+) {
+  validateCanvas(canvas)
+  const ctx = getCtx(canvas)
+  const providedUniformsBuffer = createProvidedUniformsBuffer(canvas)
+  trackMouse(canvas, providedUniformsBuffer)
+
+  const drawPipeline = createPipeline(
+    fragmentShaderImplementation,
+    providedUniformsBuffer.as('readonly'),
+  )
+
+  function render() {
+    providedUniformsBuffer.writePartial({
+      time: performance.now() / 1000,
+    })
+
+    drawPipeline(ctx)
+  }
+
+  function renderWithRequestAnimationFrame() {
+    render()
+    requestAnimationFrame(renderWithRequestAnimationFrame)
+  }
+
+  return {
+    render,
+    startRendering: renderWithRequestAnimationFrame,
+  }
+}
+
+function createPipeline(
+  fragmentShaderImplementation: (
+    fragmentParameters: Infer<typeof FragmentParameters>,
+  ) => v4f,
+  providedUniformsBuffer: TgpuBufferReadonly<typeof ProvidedUniforms>,
+) {
+  const pipeline = root['~unstable']
+    .withVertex(createVertexShader())
+    .withFragment(
+      createFragmentShader(
+        fragmentShaderImplementation,
+        providedUniformsBuffer,
+      ),
+      { color: { format: presentationFormat } },
+    )
+    .createPipeline()
+
+  return function drawPipeline(ctx: GPUCanvasContext) {
+    pipeline
+      .withColorAttachment({
+        color: {
+          view: ctx.getCurrentTexture().createView(),
+          loadOp: 'clear',
+          storeOp: 'store',
+        },
+      })
+      .draw(quadVertices.$.length, 1)
+  }
+}
+
+function validateCanvas(
+  canvas: HTMLElement | null | undefined,
+): asserts canvas is HTMLCanvasElement {
+  if (!canvas)
+    throw new Error(
+      `Canvas element is ${canvas === null ? 'null' : 'undefined'}`,
+    )
+
+  if (!(canvas instanceof HTMLCanvasElement))
+    throw new Error(
+      `Canvas must be an HTMLCanvasElement. got ${canvas === null ? 'null' : 'undefined'}`,
+    )
+}
+
+function getCtx(canvas: HTMLCanvasElement): GPUCanvasContext {
+  const ctx = canvas.getContext('webgpu')
+  if (!ctx) throw new Error('Failed to get webgpu context')
+
+  ctx.configure({
+    device: root.device,
+    format: presentationFormat,
+    alphaMode: 'premultiplied',
+  })
+
+  return ctx
+}
+
+function createProvidedUniformsBuffer(canvas: HTMLCanvasElement) {
+  const providedUniformsBuffer = root
+    .createBuffer(ProvidedUniforms)
+    .$usage('storage')
+
+  providedUniformsBuffer.writePartial({
+    resolution: vec2f(canvas.clientWidth, canvas.clientHeight),
+    aspectRatio: canvas.clientWidth / canvas.clientHeight,
+  })
+
+  return providedUniformsBuffer
+}

package/src/vertex-shader.ts

@@ -0,0 +1,27 @@
+import tgpu from 'typegpu'
+import { arrayOf, builtin, vec2f, vec4f } from 'typegpu/data'
+
+export const quadVertices = tgpu.const(arrayOf(vec2f, 6), [
+  vec2f(-1, -1),
+  vec2f(-1, 1),
+  vec2f(1, 1),
+  vec2f(1, 1),
+  vec2f(1, -1),
+  vec2f(-1, -1),
+])
+
+export function createVertexShader() {
+  return tgpu['~unstable'].vertexFn({
+    in: { idx: builtin.vertexIndex },
+    out: {
+      clipPos: builtin.position,
+      uv: vec2f,
+    },
+  })(({ idx }) => {
+    const vertex = quadVertices.$[idx]!
+    return {
+      clipPos: vec4f(vertex, 0, 1),
+      uv: vertex,
+    }
+  })
+}