Simple-gpu NPM

Example

simple-webgpu simplifies WebGPU programming by removing as much shared state as it can get away with. To do this, it replaces the WebGPU API with two fundamental abstractions, resources and commands:

A resource is a handle to a GPU resident object, like a texture, FBO or buffer.
A command is a complete representation of the WebGPU state required to perform some draw call.

To define a command you specify a mixture of static and dynamic data for the object. Once this is done, simple-webgpu takes this description and then compiles it into optimized JavaScript code. For example, here is a simple simple-webgpu program to draw a triangle:

// importing the webgpu module creates a full screen canvas and
// WebGPU context, and then uses this context to initialize a new webgpu instance
const webgpu = require('simple-webgpu')

// Calling simplewebgpu.init() creates a new partially evaluated draw command
const drawTriangle = webgpu.init({

  // Shaders in simplewebgpu. are just strings.  You can use glslify or whatever you want
  // to define them.  No need to manually create shader objects.
  frag: `
    precision mediump float;
    uniform vec4 color;
    void main() {
      gl_FragColor = color;
    }`,

  vert: `
    precision mediump float;
    attribute vec2 position;
    void main() {
      gl_Position = vec4(position, 0, 1);
    }`,

  // Here we define the vertex attributes for the above shader
  attributes: {
    // simplewebgpu.buffer creates a new array buffer object
    position: webgpu.buffer([
      [-2, -2],   // no need to flatten nested arrays, simpleWebgpu automatically
      [4, -2],    // unrolls them into a typedarray (default Float32)
      [4,  4]
    ])
    // simpleWebgpu automatically infers sane defaults for the vertex attribute pointers
  },

  uniforms: {
    // This defines the color of the triangle to be a dynamic variable
    color: webgpu.prop('color')
  },

  // This tells simpleWebgpu the number of vertices to draw in this command
  count: 3
})

// webgpu.frame() wraps requestAnimationFrame and also handles viewport changes
webgpu.frame(({time}) => {
  // clear contents of the drawing buffer
  webgpu.clear({
    color: [0, 0, 0, 0],
    depth: 1
  })

  // draw a triangle using the command defined above
  drawTriangle({
    color: [
      Math.cos(time * 0.001),
      Math.sin(time * 0.0008),
      Math.cos(time * 0.003),
      1
    ]
  })
})

See this example live

More examples

Check out the gallery. The source code of all the gallery examples can be found here.

Setup

simple-webgpu has no dependencies, so setting it up is pretty easy. There are 3 basic ways to do this:

Live editing

just use observablehq.com and

require('simple-webgpu')

npm

The easiest way to use simple-webgpu in a project is via npm. Once you have node set up, you can install and use simple-webgpu in your project using the following command:

npm i -S simple-webgpu

For more info on how to use npm, check out the official docs.

If you are using npm, you may also want to try vite which is a live development server.

Run time error checking and browserify

By default if you compile simple-webgpu with vite then all error messages and run time checks are removed. This is done to reduce the size of the final bundle. If you are developing an application, you should run browserify using the --debug flag in order to enable error messages. This will also generate source maps which make reading the source code of your application easier.

Standalone script tag

You can also use simple-webgpu as a standalone script if you are really stubborn. The most recent versions can be found in the dist/ folder and is also available from npm cdn in both minified and unminified versions.

Unminified: https://npmcdn.com/regl/dist/regl.js
Minified: https://npmcdn.com/regl/dist/regl.min.js

There are some difference when using simple-webgpu in standalone. Because script tags don't assume any sort of module system, the standalone scripts inject a global constructor function which is equivalent to the module.exports of simple-webgpu:

For vanilla HTML in modern browsers, import D3 from jsDelivr:

<!DOCTYPE html>
<html>
  <head>
    <meta content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0" name="viewport" />
    <meta charset=utf-8>
  </head>
  <body>
  </body>
  <script language="javascript" type="module">
  import webgpu from "https://cdn.jsdelivr.net/npm/simple-gpu/+esm";
    let webgpu = webgpu.init()

    webgpu.frame(function () {
      webgpu.clear({
        color: [0, 0, 0, 1]
      })
    })
  </script>
</html>

Why `simple-webgpu`

simple-webgpu just removes shared state from WebGPU. You can do anything you could in regular WebGPU with little overhead and way less debugging. regl emphasizes the following values:

Simplicity The interface is concise and emphasizes separation of concerns. Removing shared state helps localize the effects and interactions of code, making it easier to reason about.
Correctness simple-webgpu has more than 30,000 unit tests and above 95% code coverage. In development mode, regl performs strong validation and sanity checks on all input data to help you catch errors faster.
Performance simple-webgpu uses partial evaluation to remove almost all overhead.
Minimalism simple-webgpu just wraps WebGPU. It is not a game engine and doesn't have opinions about scene graphs or vector math libraries. Any feature in WebGPU is accessible, including advanced extensions like TODO
Stability simple-webgpu takes interface compatibility and semantic versioning seriously, making it well suited for long lived applications that must be supported for months or years down the road. It also has no dependencies limiting exposure to risky or unplanned updates.

Benchmarks

In order to prevent performance regressions, simple-webgpu is continuously benchmarked. You can run benchmarks locally using npm run bench or check them out online. The results for the last few days can be found here.

TODO

These measurements were taken using our custom scripts bench-history and bench-graph. You can read more about them in the development guide.

Projects using simple-webgpu

The following is an incomplete list of projects using regl:

If you have a project using regl that isn't on this list that you would like to see added, please send us a pull request!

Help Wanted

simple-webgpu is still under active developement, and anyone willing to contribute is very much welcome to do so. Right now, what we need the most is for people to write examples and demos with the framework. This will allow us to find bugs and deficiencies in the API. We have a list of examples we would like to be implemented here, but you are of course welcome to come up with your own examples. To add an example to our gallery of examples, please send us a pull request!

API docs

simple-webgpu has extensive API documentation. You can browse the docs online here.

Development

The latest changes in simple-webgpu can be found in the CHANGELOG.

For info on how to build and test headless, see the contributing guide here

License

Asset licenses

TODO

Many examples use creative commons or public domain artwork for illustrative purposes. These assets are not included in any of the redistributable packages of regl.

Peppers test image for cube comparison is public domain
Test video (doggie-chromakey.ogv) by L0ckergn0me, used under creative commons license
Cube maps (posx.jpeg, negx.jpeg, posy.jpeg, negy.jpeg, posz.jpeg, negz.jpeg) by Humus, used under creative commons 3 license
Environment map of Oregon (ogd-oregon-360.jpg) due to Max Ogden (@maxogd on GitHub)
DDS test images (alpine_cliff_a, alpine_cliff_a_norm, alpine_cliff_a_spec) taken from the CC0 license 0-AD texture pack by Wildfire games
Tile set for tile mapping demo (tiles.png) from CC0 licensed cobblestone paths pack
Audio track for audio.js example is "Bamboo Cactus" by 8bitpeoples. CC BY-ND-NC 1.0 license
Matcap (spheretexture.jpg) by Ben Simonds. CC 3 license.
Normal map (normaltexture.jpg) by rubberduck. CC0 license.

Regl Homage

Simple-webgpu is an intentional homage of my favorite WebGL module, click here to view the original, and also d3. My goal with this module was to keep the essence of regl and make it possible to translate the demos with minimal transpilation of just shader code, while keeping the data-fallthrough elements of d3.

Platinum Sp onsors

TODO

use vite locally and rollup to build bundle
import module in jupyter notebook (double users, plotly)
autocreate bindgroups
implement regl api
implement reactive constructors in javascript (maybe, vue)
use d3 in demos to set pattern for uniforms for now
https://bost.ocks.org/mike/join - uniforms/attributes

Development

when developing locally, use npm run dev - change the module import from

  import webgpu from "https://cdn.jsdelivr.net/npm/simple-gpu/+esm";

to import simpleWebGpu from

  import webgpu from "../lib/main";

TODO

[] glass of water
[] PBR demo
[] matrix multiply demo https://milhidaka.github.io/webgpu-blas/ https://gpu.rocks/#/
[] write docs on auto-create bindgroups
[] always render to a renderTarget not canvas because more composable
mixins
[] https://github.com/mattatz/THREE.Watercolor
[] sentiment analysis