WebGPU for Go in the browser (GOOS=js GOARCH=wasm): a typed API named after
the WebGPU specification, usable from any Go
program that runs in a window or a worker.
Status: released, v0.1.0 (pre-1.0: a minor version may change the API). It covers the direct API, batched command encoding (one JavaScript call per submit) and OffscreenCanvas surfaces. The go-wasmcontainers GPU host runs on it.
go get github.com/go-gfx/webgpu@v0.1.0import "github.com/go-gfx/webgpu"- Adapters and devices, refusing a fallback (software) adapter unless asked; device loss as a channel.
- Buffers (vertex, index, uniform, storage, indirect), mapping,
WriteBuffer. - Textures of every format of the specification, views, samplers,
WriteTexture(dirty-rectangle updates), texture and buffer copies. - Bind group layouts, pipeline layouts, bind groups, render and compute pipelines (sync and async), depth-stencil, blending, multisampling.
- Render passes (indexed and instanced draws, indirect draws, viewport, scissor), render bundles, compute passes.
- Error scopes and uncaptured errors as Go errors.
- Surfaces: an OffscreenCanvas with a WebGPU context, frames out as
ImageBitmaps, and a signal for browsers that have no such context.
if err := webgpu.CanvasSupport(); err != nil {
// errors.Is(err, webgpu.ErrNoCanvasContext): use another renderer
}
s, err := device.NewSurface(webgpu.SurfaceDescriptor{Width: 640, Height: 480})
tex, err := s.CurrentTexture() // render into a view of it
bitmap, err := s.Present() // transferToImageBitmap: post it to the page, or close its.CurrentView() is CurrentTexture plus CreateView(nil) for a frame
loop: it returns the same Go handles every frame, standing for the new browser
objects, and a whole frame (texture write, view, pass, submit) allocates 4
objects (TestFrameAllocs holds it to that).
A standalone OffscreenCanvas never shows itself (the specification says the
canvas is presented automatically only for a placeholder canvas): Present
moves the frame out as an ImageBitmap without a copy, for a worker to post to
its page. NewSurfaceFromCanvas takes a canvas the page transferred with
transferControlToOffscreen; the browser presents that one by itself. The
surface size is bounded by the quota (SurfaceWidth, SurfaceHeight).
CanvasSupport probes getContext("webgpu") on an OffscreenCanvas. MDN's
compatibility data lists that context in Chrome 113 (every platform from 144),
Safari 26, and Firefox 141 on Windows only. Where it returns
ErrNoCanvasContext, a program should fall back to a non-WebGPU renderer.
The browser tests read each presented frame back through a 2D canvas, pixel by
pixel, so a blank frame fails them. That includes the Linux SwiftShader lane,
where headless Chromium needs Skia on Vulkan to present at all.
A syscall/js call costs about ten times the WebGPU call it carries. A
Recorder records a whole submit in Go (buffer and texture writes
(WriteBuffer, WriteTexture, ReadBuffer, CopyTextureToBuffer: stream version 5), render and compute
passes, dynamic offsets included) as uint32 words; Submit copies them to
JavaScript once and replay.js issues the WebGPU calls:
webgpu.InstallReplay(ctx, "/webgpu-replay.js") // once; "" loads the embedded copy from a blob: URL
rec := device.NewRecorder() // reuse it frame after frame
rec.WriteBuffer(uniforms, 0, frameData)
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() // one call; the first refused command, if any
err = device.WaitSubmitted(ctx, seq) // only when the CPU must wait for the GPUThe recorder checks every command as the direct API does. replay.js
(webgpu.ReplayJS, served as webgpu.ReplayJSName) is a plain same-origin
script, so a page with script-src 'self' serves it like wasm_exec.js; it
evaluates nothing and refuses a malformed stream. Its Go mirror, wire.Decode,
reads the same format with the same checks. It is fuzzed, and a browser test
holds the two readers to the same verdict on thousands of mutated streams.
The stream format is exported as package wire, which has no GOOS
constraint. It contains the opcodes, Decode, StreamVersion and
Remap. Remap rewrites every object id of a stream through a mapping
and refuses any id the mapping does not grant. With it, a stream recorded
in one place (for example, a VM guest sending it over the
go-virtio/gpu webgpu-batch
context) can be checked and replayed by another table without a second
implementation of the format. Device.Replay(words, data, refs...)
submits such a stream once its ids name this device's objects. It is
checked with wire.Decode first, and it may name only the objects passed
in refs.
Outside the browser, NewRemoteDevice(sink, label, quota) returns a
remote device. Its creation calls, Queue.WriteBuffer and
Recorder.Submit send wire descriptors and streams to a RemoteSink, for
example a VM guest's virtio-gpu webgpu-batch context, where a real device
runs them. The checks and quotas are the browser path's, so a remote
device refuses at the call what a browser device refuses. A sink error
loses the device. WriteTexture and command encoders are not carried
(ErrRemoteUnsupported).
Read-back (stream version 4, wire.ReadBuffer). mapAsync is
asynchronous, which a replayed stream cannot express, so
Recorder.ReadBuffer(buf, offset, size) records a read: 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 GPUBuffer.mapAsync's: the buffer has MAP_READ
(which WebGPU allows only with COPY_DST, so the data is first copied there by
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
(Quota.ReadBytes, at most wire.MaxReadWindow = 64 MiB). On a remote device
the sink must be a ReadSink (SubmitRead fills the window), and
Buffer.MapAsync(ctx, MapModeRead, ...), ReadMapped and Unmap work on top
of it, one submit per map. On a browser device a Recorder is its own host and
Submit waits and maps itself.
Texture read-back (stream version 5, wire.CopyTextureToBuffer).
Recorder.CopyTextureToBuffer(src, dstBuffer, layout, size) records
encoder.copyTextureToBuffer, so a frame is read without a compute pass that
loads every texel into a storage buffer: copy the texture into a buffer
(COPY_DST, rows padded to 256 bytes, layout.BytesPerRow a multiple of
wire.CopyBytesPerRowAlignment), into a MAP_READ buffer directly or through
CopyBufferToBuffer, then ReadBuffer it. It is checked where it is recorded
and again by the host: the texture has COPY_SRC and is not multisampled, the
mip level exists, the region lies inside that level on block boundaries, and
the layout (offset, rows, images; 64-bit arithmetic, overflow refused) lies
inside the buffer. A batch.Context keeps each texture's descriptor from
Create for this and refuses a bad copy with an error wrapping wire.ErrRange
before the backend runs (webgpu.CheckCopyTextureToBuffer is the one check).
The host side is package batch (no GOOS constraint): a Context
holds a guest's private id table over a Backend and offers the three
messages every transport carries, Create, Destroy and Stream. Ids are
translated before the backend sees anything (a stream can only name objects its
own context created), a failed message loses the context, and the reads of a
stream are checked before it runs: a Reader backend, a window within the
quota (Config.MaxRead, 1 MiB by default), MAP_READ buffers, ranges inside
the buffers and the window. Before the backend is called, wire.CheckRanges
refuses what wire.Decode cannot know, with wire.ErrRange: a WriteBuffer
or CopyBufferToBuffer range outside its buffer, an indirect dispatch or draw
whose arguments leave the buffer, a Dispatch above
maxComputeWorkgroupsPerDimension (65 535, or Config.MaxWorkgroups);
Device.Replay applies the same rule to its granted buffers. A compute quota
follows: wire.CheckInvocations (Config.MaxDispatchInvocations,
Config.MaxStreamInvocations, counted at the workgroup counts times
Config.WorkgroupInvocations, the device's maxComputeInvocationsPerWorkgroup)
refuses, with wire.ErrBudget (which wraps wire.ErrRange), a stream asking
for more invocations than the quota; Context.PeakInvocations and
PeakDispatchInvocations report the largest stream and the largest dispatch
seen. An indirect dispatch takes its counts from GPU memory and
is not counted; a time budget in the host is what bounds it. A draw quota is
its render counterpart: wire.CheckDraws (Config.MaxDrawVertices per draw,
Config.MaxStreamVertices per stream) counts each Draw at vertexCount × instanceCount and each DrawIndexed at indexCount × instanceCount, sums
saturating at the largest uint64 (never wrapping), and refuses a stream above
the quota with wire.ErrDrawBudget (which also wraps wire.ErrRange) before the
backend is called, so nothing of it runs; Context.PeakVertices and
PeakDrawVertices report the largest stream and the largest draw seen. Indirect
draws and the draws inside executed render bundles are not counted. WebGPU validation
stays the second line. A loop that runs for seconds is not something a dispatch
count can see, and WebGPU cannot cancel submitted work, so a backend can cut it
(DeviceBackend.SetLoopBudget(batch.LoopBudget{...}), go-gfx/wgsl
transform.LoopBudget): every guest compute shader is rewritten, parse-level
only, so that each loop nest stops at Work / invocations iterations
(a power of 4, at most 2^24, at least 1024) and sets a host flag; a stream whose
flag is set fails with batch.ErrTruncated and its results are not returned.
Nothing unbounded runs: a module the host cannot bound (WGSL its parser does not
accept, a loop in a module with a vertex or fragment entry point, a rewrite the
browser refuses) is refused with batch.ErrUnbounded. A render stage cannot
write the flag, so a module with a vertex or fragment entry point is accepted,
unchanged, only if every loop in it is a constant-bound leaf loop of at most
batch.MaxRenderLoop (64) iterations, for (var i = 0u; i < 64u; i++) with
literal bounds and step, no inner loop and no assignment to i; a break on a
runtime count (if (i >= n) { break; }, n read from a storage buffer) is
fine. i < n, 65 iterations, nested loops, loop {} and while stay
refused. The refusal comes after the browser has
given its own verdict on the guest's text (an invalid module is reported as the
browser reports it). The host keeps the last bind group (maxBindGroups - 1, 3
by default) for it; a guest that uses it is refused with batch.ErrReserved.
batch.Guard is the same machinery for hosts that call the objects API
(Shader, ShaderNoWait, Pipeline, Pass, Finish, Submit,
SubmitNoWait): the wasi:webgpu host module and wasi-nn use it. Under GOOS=js,
NewDeviceBackend(device) is the
backend on a browser device. go-virtio/gpudev and the go-wasmcontainers host
module both build on it. Measured read-back round trips on an Apple GPU
(Chromium, Metal) are in docs/readback.md.
Objects are created remotely the same way. EncodeDescriptor turns a
creation descriptor (buffer, texture, view, sampler, shader module, bind
group layout, pipeline layout, bind group, render or compute pipeline)
into bytes. It names each referenced object by its replay id, in a
header (wire.SplitDescriptor), and wire.RemapDescriptor translates
those ids without reading the body. DecodeDescriptor rebuilds the
descriptor with the receiver's objects. It refuses unknown fields, a
wrong reference count and references of the wrong type, and it never
keeps an object that the body itself carries. The decoder is fuzzed
(FuzzDecodeDescriptor).
Submissions are numbered on a timeline (package timeline, shared by
Queue.Submit and Recorder.Submit): completing number n completes every
earlier one, the fence model of virtio-gpu, so many waiters cost one
onSubmittedWorkDone round trip. The package has no dependency and no notion
of a GPU.
atlas.Shelf(packageatlas, no GOOS constraint): a shelf packer that places many small images (textures, lightmaps, glyphs) in one texture.kernels/q4(no GOOS constraint): WGSL generator for a Q4_0 / Q4_1 matrix-vector product, f32, no subgroups or f16, sizes from the adapter's limits; the z axis batches vectors (tokens); fused RMSNorm, residual add and custom prologues and epilogues throughHooks.kernels/argmax: two-stage greedy sampler (lowest index on ties). Used by go-wasmcontainers/llm v0.3.1 (580 tok/s decoding SmolLM2-135M in Chromium against 514 for llama.cpp on one CPU core).Device.ReadTexture(ctx, src, width, height, bytesPerTexel): copies a region of a texture to Go memory, rows unpadded (the copy to a buffer wants rows padded to 256 bytes). For tests and screenshots, not a frame loop.
WebGPU reports most mistakes asynchronously. This package checks in Go first
and returns a *webgpu.BoundsError from the call: a WriteBuffer past the end
of its buffer, a WriteTexture region outside the mip level or a layout that
does not fit its data, a vertex buffer range past the buffer, a missing usage.
Data from untrusted sources (game maps, container guests) cannot reach the GPU
out of range without the caller being told. All size arithmetic is overflow
checked and tested on 32-bit targets.
q := &webgpu.Quota{MemoryBytes: 256 << 20, Pipelines: 256, ShaderBytes: 1 << 20}
d, err := adapter.RequestDevice(ctx, &webgpu.DeviceDescriptor{Quota: q})A quota is charged before the browser is called (texture sizes are computed by
the package, mips and samples included) and refunded on Destroy, Release
or device loss. Optional features and limits are refused unless the quota
lists them, timestamp-query included.
Methods that wait on a promise (RequestAdapter, RequestDevice, MapAsync,
PopErrorScope, OnSubmittedWorkDone, Create*PipelineAsync) block only the
calling goroutine, take a context.Context, and must not be called from a
js.FuncOf callback.
batch.DeviceBackend.Create makes shader modules, bind group layouts, pipeline
layouts, bind groups and pipelines inside a validation error scope. WGSL
that does not compile (a reserved word, a syntax error) or an object WebGPU
refuses is an error wrapping batch.ErrInvalid whose text is the browser's
message with the WGSL line and column; without the scope it was a silent
no-op that later work tripped over. TestInvalidWGSLOnGPU runs a reserved
word, a syntax error and an unknown function, and a valid control.
The descriptor, validation and quota code is platform-neutral and has every
block covered on Linux, macOS, Windows and linux/386. The calls are tested in a
real browser worker by internal/cmd/wasmbrowser, a go test -exec runner
over Playwright:
go -C internal/cmd/wasmbrowser build -o /tmp/wasmbrowser .
WEBGPU_REQUIRE_GPU=1 GOOS=js GOARCH=wasm go test -exec=/tmp/wasmbrowser ./...The browser tests render a GLQuake-shaped frame (8-bit index texture through a palette texture and a sampler, vertex and index buffers, instancing with per-instance data in a storage buffer, a depth buffer, a dirty-rectangle texture update, the same frame from a render bundle) and check every pixel. CI runs them on macOS with a GPU required (a fallback adapter fails the lane) and on Linux on SwiftShader.
Measured on an Apple M4 Max, Chromium 143, Metal adapter, in a worker. The
machine's load was 10 to 16 during these runs, so the numbers are indicative.
One syscall/js call costs about 200 ns for setPipeline, setBindGroup or
draw, against 17 ns for the same draw issued from JavaScript: the cost is
the call itself (each Value.Call decodes its method name).
CPU time per frame of n draws (setBindGroup + draw each), median of three
runs of BenchmarkFrame:
| draws | direct calls | Recorder |
the same frame in JavaScript |
|---|---|---|---|
| 100 | 80 µs | 22 µs | 13 µs |
| 1000 | 491 µs | 85 µs | 32 µs |
| 5000 | 2320 µs | 380 µs | 138 µs |
Batching is 5.8 to 6.1 times faster than direct calls from 1000 draws up. The
design estimated about 15 times, from a prototype that recorded with no checks
and no object table; the checks and the table cost the difference. It is still
2.7 times the JavaScript floor: recording costs about 40 ns per draw in wasm
(10 ns natively, BenchmarkRecordDraws), and the rest is the replay itself.
All of these timings were taken with the machine's load between 10 and 16, so
they are indicative, not final.
WriteBuffer copies through a staging array the device reuses; allocating a
fresh Uint8Array per call, as is common, was 3 to 4 times slower. Whether
the source is a 64 KiB array, a view into a 64 MiB one or into the Go
instance's own memory makes no difference: about 5 µs per 64 KiB write, all
spent in the browser's copy (BenchmarkWriteBuffer64KiBSource). An earlier
prototype that found the Go-memory view slower had measured a queue that was
backing up. A zero-copy path would save one copy per write but would depend
on wasm_exec.js internals, so writes go through the staging copy.
BSD 3-Clause, see LICENSE.