Skip to content
go-gfxPublic

About

WebGPU for Go in the browser (GOOS=js): typed API, batched command encoding replayed in one JS call per submit

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

32 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

webgpu

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.0
import "github.com/go-gfx/webgpu"

What it covers

  • 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.

Surfaces

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 it

s.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.

Batched encoding: one JavaScript call per submit

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 GPU

The 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.

Helpers

  • atlas.Shelf (package atlas, 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 through Hooks. 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.

Errors at the call, not later on the device

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.

Quotas for embedders

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.

Promises

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.

Invalid objects in batch

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.

Tests

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.

Performance

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.

Licence

BSD 3-Clause, see LICENSE.

About

WebGPU for Go in the browser (GOOS=js): typed API, batched command encoding replayed in one JS call per submit

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages