Skip to content

WebGPU (browser)

WebGPU for Go in the browser

github.com/go-gfx/webgpu is a typed Go API over the browser’s WebGPU, for any Go program built with GOOS=js GOARCH=wasm that runs in a window or a worker. It is the shared layer under the go-wasmcontainers GPU host (wasi:webgpu, wasi-nn) and the browser game renderers (go-quake1).

Released: v0.8.0. Install it with go get github.com/go-gfx/webgpu@v0.8.0. Before 1.0, a minor version may change the API. The go-wasmcontainers GPU host runs on this release.
import "github.com/go-gfx/webgpu"

g, err := webgpu.Navigator()                         // navigator.gpu
a, err := g.RequestAdapter(ctx, nil)                 // refuses a fallback adapter by default
d, err := a.RequestDevice(ctx, &webgpu.DeviceDescriptor{Quota: q})
b, err := d.CreateBuffer(webgpu.BufferDescriptor{Size: 64, Usage: webgpu.BufferUsageVertex | webgpu.BufferUsageCopyDst})
err = d.Queue().WriteBuffer(b, 0, vertices)          // range checked at the call

What it covers

  • Adapters and devices (device loss as a channel), buffers and mapping, textures of every format of the specification, views, samplers, WriteTexture for dirty rectangles, texture and buffer copies.
  • Bind group and pipeline layouts, bind groups, render and compute pipelines (sync and async), depth-stencil, blending, multisampling.
  • Render passes with indexed, instanced and indirect draws, render bundles, compute passes, error scopes, uncaptured errors.
  • Surfaces: an OffscreenCanvas with a WebGPU context, frames out as ImageBitmaps.

Errors at the call

WebGPU reports most mistakes asynchronously, on the device. The package checks first and returns a *webgpu.BoundsError from the call: a write past a buffer, a texture region outside its mip level, a linear layout that does not fit its data (the specification’s “validating linear texture data”), a missing usage. The arithmetic is overflow checked, tested on 32-bit targets, and the copy check is fuzzed against an unbounded-integer oracle.

Quotas

A Quota bounds GPU memory (texture sizes are computed by the package), pipelines, WGSL size, surface size, and the optional features and limits a device may require (timestamp-query included). It is charged before the browser is called and refunded on Destroy, Release or device loss; the go-wasmcontainers playground gives one to each untrusted container.

Batched encoding

A syscall/js call costs about 200 ns, ten times the WebGPU call it carries. A Recorder records a whole submit in Go and replays it with one call into replay.js, a plain same-origin script (it runs under script-src 'self'):

webgpu.InstallReplay(ctx, "/webgpu-replay.js")
rec := device.NewRecorder()
p := rec.BeginRenderPass(passDesc)
p.SetPipeline(pipe)
for _, s := range surfaces {
	p.SetBindGroup(0, s.group)
	p.DrawIndexed(s.count, 1, s.first, 0, 0)
}
p.End()
seq, err := rec.Submit()
err = device.WaitSubmitted(ctx, seq)

Every command is checked as in the direct API. replay.js and its Go mirror read the same format with the same checks; the Go reader is fuzzed, and a browser test holds both to the same verdict on thousands of mutated streams. Submissions are numbered on a timeline (package timeline): completing one completes every earlier one, the fence model of virtio-gpu.

The stream format is exported as package wire, which has no GOOS constraint. It contains the opcodes, wire.Decode (the Go reader) and wire.StreamVersion. It also has wire.Remap, which rewrites every object id through a mapping and refuses any id the mapping does not grant. A stream recorded in one place can then be checked and replayed against another object table without a second implementation of the format. copyTextureToTexture is also in the batch, as Recorder.CopyTextureToTexture. Adding it moved StreamVersion to 2.

Work recorded somewhere else can now reach a device in the browser:

  • Objects. EncodeDescriptor turns a creation descriptor into bytes that name every referenced object by id in a header (wire.RemapDescriptor translates those ids). DecodeDescriptor rebuilds the descriptor with the receiver’s objects. It refuses unknown fields, a wrong reference count and references of the wrong type.
  • Streams. Device.Replay(words, data, refs...) submits a stream that names only the granted objects (ReplayID gives their ids). The stream is checked with wire.Decode first.
  • The remote device. Outside the browser, NewRemoteDevice(sink, …) implements the creation calls, Queue.WriteBuffer and Recorder.Submit by sending descriptors and streams to a RemoteSink. It uses the browser path’s checks and quotas. WriteTexture and encoders are not carried; read-back is (below).

Read-back

mapAsync is asynchronous, which a replayed stream cannot express. So Recorder.ReadBuffer(buf, offset, size) records wire.ReadBuffer (opcode 34, StreamVersion 4): once the submit’s GPU work has completed, the replayer maps the range, copies it into a read window of the submit and unmaps. Submit returns the bytes in the Readback. The rules are those of GPUBuffer.mapAsync: the buffer has MAP_READ (allowed only with COPY_DST, so the data is first copied there with CopyBufferToBuffer), the offset is a multiple of 8, the size a nonzero multiple of 4, the range inside the buffer. The window is bounded per submit by Quota.ReadBytes, and never above wire.MaxReadWindow (64 MiB). On a remote device the sink implements ReadSink, and Buffer.MapAsync(ctx, MapModeRead, …) works on top of it.

Measured in Chromium on Apple Metal (one submit, replay to bytes in the window): about 124 µs for a 4 KiB read and 155 µs for 1 MiB, or 270 µs and 320 µs when the submit also runs a compute pass and the buffer copy.

The host side: package batch

Package batch (no GOOS constraint) is the host half of a batched stream, without a transport. A Context holds one guest’s private object ids over a Backend and offers the three messages every transport carries: Create, Destroy and Stream. Ids are translated before the backend sees anything, a failed message loses the context, and the reads of a stream are checked before it runs (a backend that can read, a window within Config.MaxRead, 1 MiB by default, MAP_READ buffers, ranges inside the buffers and the window). Under GOOS=js, NewDeviceBackend(device) is the backend on a browser device. go-virtio’s gpudev (v0.2.0) is built on it, and so will be the go-wasmcontainers host module.

Since v0.8.0, wire.CheckRanges refuses, before the backend or replay.js sees the stream, a WriteBuffer or CopyBufferToBuffer range outside its buffer, an indirect dispatch or draw whose arguments leave the buffer, and a Dispatch above maxComputeWorkgroupsPerDimension (65535, or batch.Config.MaxWorkgroups). Errors wrap wire.ErrRange. The check runs in batch.Context.Stream and Device.Replay; wire.RemapCmds is new, and FuzzCheckRanges fuzzes the check.

The first user is go-virtio’s webgpu-batch virtio-gpu context. A VM guest’s go-gfx/webgpu program sends its work to the gpudev host, which replays it on the browser’s GPU. That path is validated in Chromium on Apple Metal.

Measured on an Apple M4 Max, Chromium 143, Metal, CPU time per frame. The machine was loaded during these runs (1-minute load 10 to 16), so treat the numbers as indicative:

drawsdirect callsRecorderthe same frame in JavaScript
1000491 µs85 µs32 µs
50002320 µs380 µs138 µs

That is about six times faster than direct calls, against the design’s estimate of fifteen. The estimate came from a prototype that recorded with no checks and no object table.

Surfaces

if err := webgpu.CanvasSupport(); err != nil {
	// errors.Is(err, webgpu.ErrNoCanvasContext): fall back to another renderer
}
s, err := device.NewSurface(webgpu.SurfaceDescriptor{Width: 640, Height: 480})
tex, err := s.CurrentTexture()
bitmap, err := s.Present() // ImageBitmap, moved out without a copy

MDN’s compatibility data lists the WebGPU context of OffscreenCanvas in Chrome 113 (every platform from 144), Safari 26, and Firefox 141 on Windows only. Elsewhere, CanvasSupport is the signal to fall back to another renderer.

Tests

The platform-neutral code (descriptors, validation, quotas, the recorder) has every block covered on Linux, macOS, Windows and linux/386. The calls run in a real browser worker through go test -exec and Playwright. On macOS a GPU is required and a fallback adapter fails the run; Linux runs on SwiftShader. Every frame is checked pixel by pixel.