Gpu-curtains NPM

gpu-curtains

:warning: WIP

DOM 2 WebGPU rendering engine

gpu-curtains is a small, lightweight WebGPU rendering engine library.

Although it can theoretically be used as a genuine 3D engine, its main purpose is to turn HTML elements into textured planes, allowing you to animate them via WGSL shaders.

The project was initially conceived as a WebGPU port of curtains.js. It turned out to be a complete rewrite of the library instead, but with a very similar API.

Usage

You can directly download the files and start using the ES6 modules:

ES modules

import { GPUCurtains } from 'path/to/dist/esm/index.mjs'

window.addEventListener('load', async () => {
  // set our main GPUCurtains instance
  // it will handle everything we need
  // a WebGPU device and a renderer with its scene,
  // requestAnimationFrame, resize and scroll events...
  const gpuCurtains = new GPUCurtains({
    container: '#canvas'
  })

  // set the GPU device
  // note this is asynchronous
  await gpuCurtains.setDevice()

  // now create some magic!
})

You can also use one of your favorite package manager:

npm

npm i gpu-curtains

yarn

yarn add gpu-curtains

Finally, you can load the library from a CDN. You should always target a specific version (append @x.x.x) rather than the latest one in order to avoid breaking changes.

import { ... } from 'https://esm.run/gpu-curtains'
// or
import { ... } from 'https://cdn.skypack.dev/gpu-curtains'
// or use another cdn...

UMD files

In a browser, you can use the UMD files located in the dist directory:

<script src="path/to/dist/gpu-curtains.umd.min.js"></script>

Or use a CDN:

<script src="https://cdn.jsdelivr.net/npm/gpu-curtains"></script>

Documentation and examples

Basic example

HTML

<body>
    <!-- div that will hold our WebGPU canvas -->
    <div id="canvas"></div>
</body>

CSS

body {
  position: relative;
  width: 100%;
  height: 100%;
  margin: 0;
  overflow: hidden;
}

#canvas {
  /* make the canvas wrapper fits the viewport */
  position: fixed;
  top: 0;
  right: 0;
  width: 100%;
  height: 100lvh;
}

Javascript

import { Curtains, Mesh } from 'gpu-curtains';

window.addEventListener('load', async () => {
  // set our main GPUCurtains instance
  // it will handle everything we need
  // a WebGPU device and a renderer with its scene,
  // requestAnimationFrame, resize and scroll events...
  const gpuCurtains = new GPUCurtains({
    container: '#canvas'
  })

  // set the GPU device
  // note this is asynchronous
  await gpuCurtains.setDevice()

  // create a cube mesh
  const mesh = new Mesh(gpuCurtains, {
    geometry: new BoxGeometry(),
  })
  
  // this callback is executed
  // before the scene actually updates the matrix stack
  mesh.onBeforeRender(() => {
    // make it rotate
    mesh.rotation.x += 0.01
    mesh.rotation.y += 0.02
  })
})

Limitations

Since gpu-curtains is mostly made to create quads based on HTML elements, it may lack some common 3D engines features.

If you need a real 3D engine that could handle complex geometries or advanced rendering mechanics, then you should probably go with another library like three.js or Babylon.js.

Contributing

Contribution are more than welcome! Please refer to the contribution guidelines.

Acknowledgements

Some parts of the code (mostly the math classes) have been ported or adapted from other existing open source libraries like three.js and glmatrix.

Some examples are also ported and/or inspired by other online open-source WebGL or WebGPU examples. In any case the source should always be credited in the code. If a credit is missing, feel free to reach out or make a PR.

The WebGPU samples, WebGPU fundamentals and WebGPU best practices were very helpful to help with the basic concepts of WebGPU. If you want to understand a bit more how it's working under the hood, do not hesitate to check those.

A big thanks to the members of the WebGPU matrix chan that were always super kinds and very helpful as well.