vega-webgpu

What it is

Vega ships a canvas renderer and an svg renderer. This is a third one, built on WebGPU. It registers itself with Vega's renderer module, so nothing about a spec changes: the same scenegraph is drawn with GPU pipelines instead of 2D canvas calls.

The canvas renderer is the reference. Every spec in the corpus is rendered both ways and compared pixel by pixel on every commit, so a difference is a tracked defect rather than a surprise. The render gallery shows every case as each of the last ten runs on main and every release drew it, and what is still off is listed under features and roadmap.

Needs a browser with WebGPU. Without one, 'webgpu' draws with the canvas renderer, see falling back.

Use it

Script tag

The renderer registers itself when loaded after Vega.

<script src="https://cdn.jsdelivr.net/npm/vega@6/build/vega.min.js"></script>
<script src="https://vega.github.io/vega-webgpu/releases/2_0_4/vega-webgpu-renderer.js"></script>
<div id="vis"></div>
<script>
  fetch('https://vega.github.io/vega/examples/bar-chart.vg.json')
    .then(res => res.json())
    .then(spec => {
      new vega.View(vega.parse(spec), {
        renderer: 'webgpu',
        container: '#vis',
        hover: true,
      }).runAsync();
    });
</script>

Every hosted build is listed under versions, each with its own page.

Match the Vega major version. 2.0.0 and later target Vega 6. Everything before it targets Vega 5 and throws Class constructor cannot be invoked without 'new' when loaded next to Vega 6, because a renderer registers itself against whichever Vega is already on the page.

Falling back

Without navigator.gpu, 'webgpu' draws with the canvas renderer and warns. A browser can also have navigator.gpu and no adapter, a blocklisted GPU for instance, and then nothing is drawn. To fall back there too, pick the renderer from the adapter:

const renderer = (await navigator.gpu?.requestAdapter()) ? 'webgpu' : 'canvas';
new vega.View(vega.parse(spec), { renderer, container: '#vis' }).runAsync();

Config

Options live on view._renderer.wgOptions and can be changed between frames.

const view = new vega.View(vega.parse(spec), { renderer: 'webgpu', container: '#vis' });
view._renderer.wgOptions.debugLog = true;

renderBatch and simpleLine were removed in 2.0.0. The line mark batches its segments unconditionally now, so neither had anything left to switch.

Feature completeness

All twelve of Vega's mark types are drawn: arc, area, group, image, line, path, rect, rule, shape, symbol, text and trail. Fill, stroke, opacity, clipping, corner radii, symbol shapes and rotation, and text layout all work on every mark that has them. The table is the properties that used to stop at some marks, and each now reaches every mark that has it.

Every mark name is a link into the playground, where you can tick these properties on and off and watch canvas and WebGPU draw the same spec side by side.

Known differences from canvas

• No seam between abutting fills. Two polygons sharing an edge, a choropleth's counties for instance, come out with no line between them. Canvas fills each polygon separately so about a quarter of the background survives on the shared edge, which is the seam you are used to seeing. One multisampled pass covers that edge completely. Ask for the border with a stroke instead, which is clearer about the intent and matches everywhere. Reproducing the seam is planned for a release after 2.0.0.
• Edges of triangulated marks. arc, area, path and shape take their edge coverage from MSAA, which expresses quarter steps, so an edge landing on a pixel boundary can read a quarter light or heavy against canvas. rect, rule, symbol and line segments compute coverage analytically and do not have this.
• Maximum canvas size. The canvas is a GPU texture, so its device pixels are capped at the adapter's maxTextureDimension2D, usually 16384 on a desktop GPU and never less than 8192. A view past that draws at a lower pixel ratio that fits, softer than asked for, with one warning. Keep width and height times devicePixelRatio under the cap for full sharpness.
• An erasing operator inside a clip path. source-in, destination-in, source-out, destination-atop and copy clear what lies outside the source, and inside a clip path they clear the path's whole bounding box where canvas clears only the path. Queued for 2.1.0.

Roadmap

Broad strokes. The full list, with the measurement behind each item, is in ToDo.md.

Set up locally

git clone https://github.com/vega/vega-webgpu.git
cd vega-webgpu
npm install
npm run build     # UMD, minified and ESM bundles plus type declarations, into build/
npm run serve     # serve the repo at http://localhost:5500

Then open http://localhost:5500/test/?spec=bar&renderer=webgpu&version=dev to run the local build against any spec in test/specs-valid. The page can show canvas and WebGPU side by side and a pixel diff between them.

Versions

Each build is hosted here and can be loaded straight from a script tag.