vega-webgpu-renderer

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. What is still off is listed under features and roadmap.

Needs a browser with WebGPU. If navigator.gpu is undefined the renderer will not register, so keep canvas as the fallback.

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://kanadaat.github.io/vega-webgpu/releases/1_2_0/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.

npm

Not published yet. Until it is, take a hosted build with the script tag above.

npm install vega-webgpu-renderer

import 'vega-webgpu-renderer'; // registers the 'webgpu' renderer

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

Falling back

Pick the renderer once, at view construction.

const renderer = navigator.gpu ? '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. What follows is the properties that do not yet reach every mark.

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.

Where a gradient is not supported the mark draws a flat colour from the gradient's first stop. Where strokeDash is not read the stroke draws solid, which is most visible on a dashed axis grid, since Vega renders those as rule marks.

strokeJoin and strokeMiterLimit are read by nobody. Triangulated marks miter at Vega's default limit of 10 and the rest join round, so only a spec that asks for something other than the default differs.

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.
• A blend mode needs an opaque backdrop. WebGPU's fixed function blending cannot express the term that leaves a source colour unchanged where the backdrop is empty, so a blended mark over a fully transparent background comes out dark where canvas leaves it alone. Charts normally set a background, and with one the four supported modes match canvas exactly.
• Downscaled images. The GPU samples bilinearly where canvas box filters a large reduction, so an icon shrunk about five times is softer than canvas draws it.
• Maximum canvas size. WebGPU caps a texture at maxTextureDimension2D, 8192 on most GPUs. A view whose device pixels exceed that drops its pixel ratio to fit and draws softer, with a warning. A view over the cap at ratio 1 cannot be drawn at all and falls back with a warning.

Roadmap

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

Set up locally

git clone https://github.com/KaNaDaAT/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.