DEV Community: GoGPU

A Shader Loop That Never Ran: What GPU Readback Found in gogpu/naga, a Go WGSL Compiler

Andrey Kolkov — Tue, 03 Nov 2026 17:07:23 +0000

Here's a WGSL loop:

for (var j = 0u; j < 4u; j++) {
    result[j] = j + 1u;
}

Until v0.20.3 in October, naga, our shader compiler written in Go, turned it into DXIL that never ran the loop. Microsoft's validator looked at the module and said it was valid. On an Intel and an NVIDIA GPU the loop body didn't execute once.

The validator wasn't wrong. That's the interesting part.

What the validator saw

This is the DXIL that naga v0.20.2 writes for that loop, trimmed to the lines that matter, with my comments on the right:

  %2 = alloca i32, align 4           ; var j
  br label %3
  ...
  %5 = load i32, i32* %2, align 4    ; read j for "j < 4"
  %6 = icmp ult i32 %5, 4
  br i1 %6, label %11, label %12

The variable j gets memory, and the very first thing the loop does is read it. Nothing ever stored the 0. Reading uninitialized memory is legal in LLVM IR, so every instruction here is well formed, the types match, the control flow is structured. IDxcValidator checks exactly those things and reports VALID (S_OK).

What it doesn't check is whether the module computes what the source says. No static validator does, not DXC's and not spirv-val. They answer "can a driver run this?", and the answer was yes. The driver ran it, j started as whatever was in that memory, and the loop exited before its first iteration.

naga v0.20.3 fixed three bugs of this kind in the DXIL backend:

The shader	What the DXIL did
`for (var j = 0u; j < 4u; j++)`	never stored the initializer; the loop didn't run
`for (var j = i; j < n; j++)`	an optimization pass deleted the initial store, then noticed the loop also writes `j`; the loop started from an uninitialized `j`
`v[i] = v[i] + 1u` on a local vector	a run-time index always picked `v.x`

For this article I compiled all three shaders with v0.20.2 again. All three come back VALID (S_OK).

Our own tests missed them too. We compare naga's text output with Rust naga's and its DXIL with DXC's, and none of that asks what the shader computes. What found them was a one-off experiment: run the shaders on real GPUs through Direct3D 12 and read the buffers back.

What naga is

naga reads WGSL, the WebGPU shading language, and writes SPIR-V for Vulkan, MSL for Metal, GLSL for OpenGL, HLSL for Direct3D, and DXIL for Direct3D 12. The DXIL is emitted directly, without DXC or LLVM. It's plain Go with no CGO, so it cross-compiles like any other Go package.

package main

import (
    "fmt"
    "log"

    "github.com/gogpu/naga/dxil"
    "github.com/gogpu/naga/hlsl"
    "github.com/gogpu/naga/msl"
    "github.com/gogpu/naga/spirv"
    "github.com/gogpu/naga/valid"
    "github.com/gogpu/naga/wgsl"
)

const source = `
@group(0) @binding(0) var<storage, read_write> result: array<u32>;

@compute @workgroup_size(1)
fn main() {
    for (var j = 0u; j < 4u; j++) {
        result[j] = j + 1u;
    }
}
`

func main() {
    module, _, err := wgsl.Parse(source, wgsl.ParseOptions{})
    check(err)
    _, err = valid.Validate(module, valid.Options{})
    check(err)

    spv := must(spirv.Compile(module, spirv.Options{}))   // Vulkan
    metal := must(msl.Compile(module, msl.Options{}))     // Metal
    hlslSrc := must(hlsl.Compile(module, hlsl.Options{})) // Direct3D, through FXC or DXC
    blob := must(dxil.Compile(module, dxil.Options{}))    // Direct3D 12, no DXC needed

    fmt.Printf("SPIR-V %d bytes, MSL %d bytes, HLSL %d bytes, DXIL %d bytes\n",
        len(spv), len(metal), len(hlslSrc), len(blob))
    fmt.Println(metal)
}

// must returns a backend's output and stops on its error.
func must[T, I any](out T, _ I, err error) T {
    check(err)
    return out
}

func check(err error) {
    if err != nil {
        log.Fatal(err)
    }
}

With naga v0.21.2 it prints SPIR-V 1240 bytes, MSL 917 bytes, HLSL 667 bytes, DXIL 2960 bytes, then the Metal source. The zero value of every options struct is the safe choice: bounds checks are on and workgroup memory is zeroed. The SPIR-V, MSL and HLSL writers also give every loop an iteration limit, because a loop the driver's compiler can prove never ends is undefined behavior, and the compiler is then free to delete it, bounds checks included. Two of those show up in the Metal output:

while(true) {
    if (metal::all(loop_bound == uint2(0u))) { break; }
    ...
    result[metal::min(unsigned(_e6), (_buffer_sizes.size0 - 0 - 4) / 4)] = _e8 + 1u;
}

Keep an eye on that metal::min. It's a fix from this month, and it comes back later.

naga takes its IR and much of its design from Rust naga, the shader compiler of Rust wgpu, which is the core of WebGPU in Firefox, Servo and Deno. We run Rust naga's 172-shader WGSL test corpus, compare our output with Rust's wherever Rust writes the same format (SPIR-V only structurally so far), and record every difference with its reason. Rust naga has no DXIL backend, so for DXIL the references are DXC and Mesa. naga's main user is gogpu/wgpu, a WebGPU implementation in Go, which compiles its WGSL shaders with naga in its default pure-Go build.

Running the output instead

After v0.20.3 we turned that experiment into a permanent test corpus: small compute shaders, each paired with the exact values a GPU has to write when it runs them. It lives in testdata/readback and has 55 cases today, mostly loops, function calls and local variables. Each case is a .wgsl file and a .json file:

{
  "format": 1,
  "desc": "for-loop counter declared in the loop header writes 1..4; the sentinel after them stays",
  "entry": "main",
  "workgroups": [1, 1, 1],
  "bindings": [
    {"binding": 0, "kind": "storage-rw", "len": 5, "fill": "0xDEADBEEF",
     "expect": [[1, 2, 3, 4, "fill"]]}
  ]
}

Three habits made the corpus useful:

Sentinels. Every output buffer starts filled with 0xDEADBEEF, and the expected values say where it has to survive. A loop that runs one time too many, or a store through the wrong index, shows up as a missing sentinel.

Inputs from buffers. Most cases read their inputs from a storage buffer, so the compiler can't fold the work away at compile time, and a few, like collatz-lit.wgsl and collatz-rt.wgsl, test the same computation both ways. The WebGPU conformance test suite uses the same trick.

Known failures with a card. A case can list a backend it currently fails on, with the issue that tracks it. The run stays readable while the bug is open, and the entry goes away with the fix.

naga can't drive a GPU itself, so the work is split. naga checks that every case is well formed and compiles on every backend, and runs spirv-val, glslangValidator, dxc and IDxcValidator on the output where they're installed. wgpu runs the corpus on its GPUs before naga releases that touch a backend, with a Go workspace (go.work) pointing at the naga candidate, so a change runs on real hardware before it's tagged. That runner still lives outside the wgpu repository; moving it in is planned, and then anyone can run the corpus on their own GPU.

For v0.21.1 the corpus ran on eight backend and adapter pairs:

Backend	Adapters
Vulkan	Intel Iris Xe, NVIDIA CMP 30HX
Direct3D 12, HLSL through FXC	Intel Iris Xe, NVIDIA GTX 1660 SUPER
Direct3D 12, naga's DXIL	Intel Iris Xe, NVIDIA GTX 1660 SUPER
OpenGL ES	Intel Iris Xe
wgpu's software backend	CPU

There's no Mac in that list. Metal is covered by wgpu's own tests on a macOS CI runner, which is where the third bug below turned up.

What it caught

Local arrays that forgot their initializers. wgpu found this one with a vertex shader that picks its corners from local arrays. The same shape, cut down:

@vertex
fn vs(@builtin(vertex_index) v: u32) -> @builtin(position) vec4f {
    var xs = array<f32, 6>(-1.0, 1.0, -1.0, -1.0, 1.0, 1.0);
    var ys = array<f32, 6>(-1.0, -1.0, 1.0, 1.0, -1.0, 1.0);
    return vec4f(xs[v % 6u], ys[v % 6u], 0.0, 1.0);
}

On naga v0.21.0 the DXIL for this has two alloca instructions and not a single store, so every index reads uninitialized memory, and the validator again says VALID (S_OK). wgpu's shader drew nothing on Intel. The bug was there since at least v0.17.16. Since v0.21.1 naga stores the initializers: 12 stores for this shader, checked on v0.21.2.

A loop-carried variable read as if the loop ran once. naga's DXIL backend turns local variables into SSA values where it can. When every access to a variable sat in one block inside a loop, and that block read the variable before writing it, the pass treated the block as running only once:

var x: u32;
for (var i = 0u; i < n; i++) {
    x += i + 1u;
    dst[i] = x;   // want 1, 3, 6, 10. DXIL wrote 1, 2, 3, 4.
}

Every iteration saw the value from before the loop. This one shipped in every release since v0.17.4. The corpus case for it also checks shapes the old code got right, such as variables read after the loop or updated only in branches, so the fix can't quietly break those.

The v0.21.1 run compared every result with the same run on v0.21.0. 54 of the 55 cases ran on each of the eight pairs (one needs shader-f16, which the runner skipped), 432 results in all. Seven changed, all on DXIL, all from fail to pass:

Backend and adapter	v0.21.0	v0.21.1
Direct3D 12 + naga's DXIL, Intel Iris Xe	50 of 54 pass	54 of 54
Direct3D 12 + naga's DXIL, GTX 1660 SUPER	51 of 54 pass	54 of 54
the other six pairs	unchanged	unchanged

Not everything in that run was green, and both versions failed the same cases: two workgroup-memory cases on the CMP 30HX under Vulkan (not diagnosed yet; Intel passes them), one known OpenGL ES failure, and 15 of the 54 in wgpu's software backend (11 failures, 4 already known). For a release gate that's the point: nothing got worse.

An out-of-bounds write on Metal. wgpu has hand-written readback tests too. One of them, TestStorageBufferOutOfBoundsContained, writes past the end of a storage binding and then checks that the binding next to it is untouched. WGSL allows an implementation to clamp such an access, and wgpu's Metal backend asks naga to clamp every index into a buffer.

On the macOS CI runner the test failed. For a plain var<storage> a: array<u32>, naga's MSL used the index as it was, and the write landed in the next binding. Only a runtime-sized array at the end of a struct got clamped. v0.21.2 clamps every index into a runtime-sized array; that's the metal::min from the output above. The unclamped MSL was perfectly valid MSL.

When Rust naga and the spec disagree

While fixing the Metal bug I noticed that our bound was computed from the array's stride and Rust naga's from the element's size. I switched to Rust's form and called ours a defect.

It wasn't. WGSL defines how many elements a runtime-sized array has, and calls it NRuntime: the buffer binding's size minus the array's offset, divided by the stride, rounded down. arrayLength must return exactly that.

The two forms differ when an element is smaller than its stride and the binding ends partway through the last stride. Take array<vec3<f32>>: each element is 12 bytes and the stride is 16. On a 28-byte binding the spec says there is truncate(28 / 16) = 1 element. Rust naga's MSL computes 1 + (28 - 12) / 16 = 2, because a second vec3 would fit in bytes 16 to 27. That's true about memory and wrong about WGSL.

The correction came from the wgpu side, and wgpu's vec3 test now pins it: its comment quotes the spec's NRuntime and requires arrayLength to follow it. v0.21.2 uses the spec's count for both the clamp and arrayLength, which is what naga's HLSL, DXIL, GLSL and SPIR-V output already did. On the macOS CI runner, a 28-byte array<vec3<u32>> binding now reads arrayLength back as 1 (run result). The difference from Rust is written down in the code, in the tests that pin the bound, and in the CHANGELOG.

So this is how we decide now. Where the spec defines a value or an error, the spec decides. Rust naga decides what the spec leaves open, like the shape of the IR or the wording of an error message. When we differ from Rust, we assume the bug is ours until we've read the spec. After that it might be theirs.

What I'd do differently

Run the output from the first day of a backend. We had validators, golden files and Rust parity long before we had a GPU in the loop. All three check that the output looks right. Only running it checks that it is right.

Read a green validator as "legal", not "correct". It's a gate worth having, and it says nothing about values.

Make the expected values hard to fake. Sentinels in every slot that shouldn't change, inputs from buffers, and several shapes per bug, including the ones the old code already handled.

What's next

DXIL is opt-in in wgpu (GOGPU_DX12_DXIL=1). The default Direct3D 12 path is HLSL through FXC, so DX12 users on that path were never affected by the DXIL bugs above.

Before we call DXIL stable, the shaders of gg, our 2D graphics library, have to pass the validator, readback has to be green on Intel and NVIDIA, and no silent bug may be known. Two are known and open right now:

more shapes of the local-initializer bug: indexed vectors, arrays of arrays, zero-initialized arrays of vectors, and struct or array variables of a helper function called inside a loop;
primitive_index reads wrong in fragment shaders on Intel, probably because the DXIL doesn't mark fragment system values as non-interpolated.

If naga compiles one of your shaders wrong, the corpus format is documented. A WGSL file plus the values it should produce is the most useful bug report we can get.

naga: github.com/gogpu/naga · pkg.go.dev

The Go gopher was designed by Renée French and is licensed under CC BY 4.0.

go get github.com/gogpu/naga@v0.21.2
go install github.com/gogpu/naga/cmd/nagac@latest
nagac -o shader.spv shader.wgsl

gogpu/ui v0.1.54: We Built Flutter's Gesture System in Pure Go — Arena, Recognizers, and All

Andrey Kolkov — Thu, 13 Aug 2026 16:33:34 +0000

Series: Building Go's GPU Ecosystem

Recent articles:

Enterprise Render Pipeline — Layer Tree, Damage Tracking, 0% GPU Idle

Extracting a GPU Compositor — Patterns from Flutter and Chromium

Pure Go 3D Renderer Embedded Inside a GUI Widget

Google Says Go Is Ideal for AI-Assisted Engineering

The Problem: Every Widget Reinvented Click Detection

Our GUI toolkit has 27 widgets — buttons, checkboxes, sliders, text fields, dropdowns, dialogs, tab views, tree views, data tables, docking panels, and more — and each one implemented its own click/drag/selection logic from scratch. Button tracked pressed state. Slider tracked dragging. TextField had its own MouseDrag handler. No code was shared. No disambiguation existed.

When we wanted to add text selection to TextField (drag to select, double-click to select word, triple-click to select all), we realized the ad-hoc approach couldn't scale. What happens when a TextField is inside a ScrollView? Both want drag events. Who wins?

Flutter solved this problem in 2017 with the GestureArena. We decided to port the same architecture to Go.

What We Built

The Gesture Arena

The arena is the core disambiguation mechanism. When a pointer goes down, all widgets under the pointer register their gesture recognizers in the arena. The recognizers compete:

First to accept wins. If a recognizer is confident it detected its gesture (e.g., drag exceeded the slop threshold), it accepts and all others are rejected.
Last to not reject wins. If everyone else rejects (e.g., no movement for drag), the remaining recognizer wins by default.
Sweep after pointer up. If no one accepted, the first member wins as a last resort.

// Widget implements gesture.GestureAware
func (w *Widget) GestureHitTest(pos geometry.Point) []gesture.Recognizer {
    return []gesture.Recognizer{w.clickRec}
}

Four Recognizers + VelocityTracker

Recognizer	What it detects	Used by
ClickRecognizer	Single/double/triple click with timing	Button, Checkbox, Radio
DragRecognizer	Pan, horizontal, vertical drag with velocity	Slider, SplitView
LongPressRecognizer	Press-and-hold (500ms, frame-based)	Future: context menu
TapAndDragRecognizer	Click counting + drag in one recognizer	TextField
VelocityTracker	Least-squares velocity for fling detection	ScrollView momentum

Per-Device Thresholds

Mouse and touch have different precision. A 1px movement on a mouse is intentional; on a touchscreen it's noise. We use the same constants Flutter validated against millions of users:

Parameter	Mouse	Touch
Drag threshold (slop)	1px	18px
Double-click timeout	300ms	300ms
Double-click distance	4px (Chromium)	100px
Anti-bounce minimum	40ms	40ms

Unified Pointer Pipeline

We replaced the legacy mouse callback path with a single PointerEvent-based pipeline:

Platform → PointerEvent → HandlePointerEvent
    ├── Gesture Arena (recognizer dispatch for GestureAware widgets)
    └── Derived MouseEvent (existing widgets continue working unchanged)

Every pointer event flows through this single path. No dual dispatch. Existing widgets receive MouseEvent as before — derived from the same PointerEvent that feeds the arena.

Container Widget Hit-Testing

The hardest bug we hit: a Collapsible widget (parent) and a Checkbox (child) both had ClickRecognizers. The parent won the arena and silently dropped clicks meant for the child.

The fix: GestureHitTest(pos geometry.Point) receives widget-local coordinates. Container widgets only return recognizers when the pointer is in their interactive region:

// Collapsible returns recognizer ONLY for header clicks
func (w *Widget) GestureHitTest(pos geometry.Point) []gesture.Recognizer {
    headerRect := geometry.NewRect(0, 0, w.Bounds().Width(), w.headerHeight)
    if !headerRect.Contains(pos) {
        return nil // Content-area click → child widgets handle it
    }
    return []gesture.Recognizer{w.clickRec}
}

TextField: The Full Story

TextField was our proof-of-concept. Before v0.1.54, it could place a cursor on click. That's it. No selection, no word selection, no clipboard.

Now:

Click to place cursor (with Shift+Click for range extension)
Drag to select text character-by-character
Double-click to select word (uses wordBoundsAt() with Unicode word boundaries)
Triple-click to select all text
Double-click + drag for word-by-word selection
Ctrl+C/V/X for OS clipboard (Win32, macOS, Linux)

All of this through one TapAndDragRecognizer that provides consecutiveTapCount on every callback — exactly how Flutter's TextSelectionGestureDetector works.

OS Clipboard

We added widget.ClipboardProvider — a DI interface (same pattern as our SoundPlayer) that bridges widget clipboard requests to the platform:

// In widget package — no platform imports
widget.ClipboardWrite("copied text")
text := widget.ClipboardRead()

// Desktop layer registers the platform implementation
widget.RegisterClipboardProvider(gogpuApp) // Win32/macOS/Linux

Ctrl+C copies to system clipboard. Ctrl+V pastes from it. Works across applications.

Signals Integration

Gesture state is exposed as opt-in reactive signals:

dragRecognizer := gesture.NewDragRecognizer(gesture.DragConfig{
    OnDragStart: handleStart,
}, gesture.WithDraggingSignal(isDragging))

// Widget binds to signal for reactive redraw
state.BindToScheduler(isDragging, widget, scheduler)

Bool signals suppress no-op notifications. Point signals fire on every change. Frame-based timers (no goroutines) for long press.

Numbers

~8,300 LOC added (gesture/ package + widget migrations + clipboard + tests)
124 gesture tests, 96% coverage
20 widgets implement GestureAware with GestureHitTest
0 goroutines in the entire gesture system — single-threaded by design
5 enterprise references studied: Flutter (source code verified), Chromium, GTK4, Qt6, Android

What's Next

The gesture system is designed for multi-touch from day one. PointerEvent carries PointerID and PointerType (mouse/touch/pen). When Android support lands (@besmpl is working on it), pinch-to-zoom and multi-finger gestures will plug into the same arena.

Context menu (right-click) is the next visible feature. The gesture infrastructure supports any button — ClickRecognizer just needs a ButtonRight config.

gogpu/ui is an enterprise GUI toolkit for Go with GPU-accelerated rendering. Zero CGO, 220K+ LOC, 70 packages, 7,800+ tests.

Help Us Build Go's GUI Future

The gesture system is the kind of infrastructure that needs real-world validation. We tested with our gallery and examples, but the edge cases live in your applications.

Try it. Clone the repo, run the gallery, drag-select some text, double-click a word. If something feels wrong — file an issue. If it feels right — even better. Tell us.

git clone https://github.com/gogpu/ui.git && cd ui
GOGPU_GRAPHICS_API=vulkan go run ./examples/gallery/

Star the repo. It sounds small, but GitHub stars are how Go developers discover projects. We're listed in awesome-go — every star helps us stay there.

Spread the word. A mention in your team's Slack, a retweet, a discussion with a colleague who's frustrated with GUI options in Go. Most Go developers don't know a pure Go GUI toolkit with GPU rendering exists.

Contribute. The gesture system is designed for extensibility. Build a custom recognizer, add a new widget, improve accessibility, test on your hardware. Check CONTRIBUTING.md. @besmpl contributed 20+ PRs across the ecosystem including Android arm64 support — contributors make this project better.

Support the project. If gogpu saves you from CGO hell or fills a gap in Go's ecosystem, consider supporting on Open Collective. Open source is free to use but not free to build.

The gogpu ecosystem is 1.25M+ lines of pure Go with zero CGO. gogpu/ui alone: 220K+ LOC, 70 packages, 7,800+ tests. Five GPU backends. Three platforms. One goal: make Go the best language for building desktop applications.

GitHub · Discussions · Release v0.1.54 · awesome-go

GoGPU: Extracting a GPU Compositor in Pure Go — Patterns from Flutter and Chromium

Andrey Kolkov — Tue, 11 Aug 2026 15:12:05 +0000

We had a suspicion the compositor was in the wrong package. But it worked, there was only one consumer, and refactoring a GPU compositor is genuinely hard. So we shipped it and moved on.

Then the 3D renderer arrived. Then the overlays broke. Suspicion turned into certainty — at the worst possible time.

This is the story of that migration, and what we learned from Flutter, Go stdlib, and Chromium along the way.

The Setup: a Compositor Hidden Inside a Drawing Library

GoGPU is a Pure Go GPU ecosystem — 1.25M lines of code, zero CGO. The architecture has three layers:

gogpu    — app framework (windowing, events, lifecycle)
gg       — 2D graphics (paths, text, GPU SDF, rasterizer)
wgpu     — WebGPU implementation (Vulkan/DX12/Metal/GLES/Software)

When we first built GPU-accelerated rendering for gg, the compositor logic naturally ended up inside gg. It was the only consumer. It owned the render target, the blit pipeline, the MSAA resolve, the damage tracking. It decided when to clear vs preserve content.

This is an ownership inversion. In every enterprise graphics stack — Chromium, Flutter, GTK4 — the compositor owns the render target and content cache. The drawing library just records draw commands into whatever surface it's given:

Framework	Drawing library	Compositor	Who owns the surface?
Chromium	Skia	cc/ (tile manager)	Compositor
GTK4	Render nodes	GSK	Compositor
Flutter	Dart Canvas	flow/	Compositor
GoGPU (before)	gg	gogpu	gg ← wrong

We suspected this wasn't right. But gg was the only renderer, it worked, and the refactoring would be complex. So we shipped it.

The Breaking Point: Three Problems, One Root Cause

Problem 1: Damage rects were single-source

Damage tracking already lived in gogpu — but as a simple passthrough. gg called SetDamageRects() with its dirty regions, gogpu forwarded them to the platform compositor via VkPresentRegionsKHR. One source, one consumer, worked fine.

Then g3d arrived. A 3D scene rotating at 60fps sends full-viewport damage. But SetDamageRects only accepted one set of rects — from gg. When gg rendered a HUD overlay on top of a g3d scene, only the HUD's damage was reported. The g3d viewport outside the HUD? Stale frames on Wayland compositors. Confirmed by @porjo on Asahi Linux (g3d#22) — visible mosaic artifacts because Mesa's wl_surface_damage_buffer only updated the HUD area.

So we redesigned the damage system from scratch. SetDamageRects (single source, simple passthrough) was replaced with RegisterDamageSource — each renderer registers as a named source, reports its own damage per frame, and gogpu unions all sources at present time. Chromium's DamageTracker uses the same union pattern. That was ADR-065 — not a refactor, a reimplementation.

Problem 2: Two overlays, two libraries

We had two independent debug overlay implementations:

gg had a damage overlay (damage_debug.go) — green flash-and-fade on dirty regions (GOGPU_DEBUG_DAMAGE)
ui had a dirty widget overlay (debug_dirty.go) — cyan rectangles on repainted widgets (GOGPU_DEBUG_DIRTY)

Both worked fine in isolation. Each had its own env var, its own rendering logic, its own fade effects. And neither knew about the other. A g3d-only app had zero debug overlays — no damage visualization, no FPS counter, nothing.

The fix: move overlays to the compositor level. A g3d-only app without gg still needs overlays. A multi-renderer app (gg + g3d) needs a unified overlay that sees damage from all sources. That was ADR-066 — a pluggable DebugOverlay system at the compositor level, with built-in damage and FPS overlays.

Problem 3: The move that broke everything

ADR-065 and ADR-066 shipped together in v0.51.0. Damage sources worked. Overlays worked — until the content was idle and the overlay had a 400ms fade animation.

1. Overlay fade: NeedsAnimationFrame() → RequestRedraw()
2. Next frame: gg says "nothing dirty" → no GPU commands
3. gg owns the render target → no commands = frame skipped
4. Overlay never draws → animation freezes

The compositor (gogpu) couldn't render overlays independently because gg owned the surface. Without gg's cooperation, the compositor couldn't even decide whether to clear or preserve the render target. The Vulkan spec says acquired swapchain images have UNDEFINED content — so without gg drawing, the overlay rendered on garbage.

Three problems, one root cause: gg owned what the compositor should own. The shortcut that "worked fine" for one consumer became a blocking architectural problem when the second and third consumers appeared. Every enterprise reference confirmed what we'd only suspected — the compositor must own the render target, not the drawing library.

Delaying further would have meant building workarounds. Each workaround would cement the wrong architecture deeper. So we stopped delaying.

Phase 1: Moving the Compositor Out of gg (ADR-067)

The first step was getting the compositor code out of gg and into gogpu where it belongs.

We introduced a compositor-owned composition texture:

Before:
  swapchain acquired → gg renders directly → present
  (gg decides Clear/Load, gg owns MSAA resolve)

After:
  swapchain acquired → gogpu clears composition texture
  → gg/g3d render INTO composition texture (they don't know)
  → gogpu draws overlays on top
  → gogpu blits composition texture → swapchain → present

Key insight: content renderers don't need to know about the compositor. Context.SurfaceView() returns the composition texture view instead of the swapchain view. From gg's perspective, nothing changed — it renders to a TextureView, same as before.

Overlay-only frames became first-class. When content is idle but an overlay is animating, the compositor uses LoadOpLoad (preserve) instead of LoadOpClear, draws the overlay on the preserved content, and presents. No cooperation from gg needed.

Phase 2: Extracting internal/compositor/ (ADR-069)

After moving compositor logic into gogpu, we had ~2,500 LOC of compositor code mixed with ~4,000 LOC of application framework in the same package. Time for the second step: extract it into internal/compositor/.

Research first

Before writing extraction code, we studied three references:

Flutter's flow/ (~22K lines) — concrete structs, unidirectional deps (shell/ → flow/, never reverse), GPU resources borrowed per frame through a callback. Closest to our situation.

Go stdlib ssa.Func (41 fields) — the largest internal/ split in Go. Struct ownership + Frontend callback interface. Parent creates the struct, calls methods. Internal package calls back through a minimal interface when it needs the parent.

Chromium cc/ (~190K lines) — interface-heavy dependency injection with *Client/*Delegate abstract classes everywhere. A C++ necessity, over-engineered for Go internal/.

What we actually built

The compositor isn't a single god-struct. It's a set of focused types that the root package composes:

gogpu/ (root package, renderer.go)
│
├── RenderTarget {
│     damageSources  []*compositor.DamageSource
│     blitPipeline    compositor.BlitPipeline
│     compositeState  compositor.CompositeState
│   }
│
└── internal/compositor/
    ├── blit.go            — BlitResources, BlitDrawRecorder interface
    ├── blit_pipeline.go   — BlitPipeline, CompositeState
    ├── damage_source.go   — DamageSource, per-renderer damage tracking
    ├── damage_scissor.go  — pure geometry: rect union, scissor clipping
    ├── damage_overlay.go  — DamageDebugOverlay (damage rect visualization)
    ├── fps_overlay.go     — FPSDebugOverlay (frame rate counter)
    ├── overlay_pipeline.go — shared GPU pipeline for overlays
    └── shader.go          — WGSL shader sources

Content renderers (gg, g3d) implement one interface:

type BlitDrawRecorder interface {
    RecordBlitDraws(pass *wgpu.RenderPassEncoder)
}

The compositor owns the render pass lifecycle. Renderers just record their draws.

The numbers

renderer.go: 2,174 → 1,892 lines (-282 LOC of compositor logic removed)
internal/compositor/: 2,357 LOC (self-contained subsystem)
Root package wiring: 194 LOC (thin delegation)

Zero public API change. All App, Context, RenderTarget types stayed in the root package. RegisterDamageSource() return type narrowed to gpucontext.DamageReporter interface — which external consumers already used. No breaking change.

Rules That Emerged

These are now enforced in CI:

1. No type aliases for migrated types. type X = internal.X is for transitional migration only. We changed return types to interfaces instead.

2. Call internal directly. No unexported wrapper functions around internal/ calls. At call sites: r.blitPipeline.Init(device, format, shader), not an unexported initBlitPipeline() wrapper.

3. Unidirectional deps, enforced in CI:

- name: Compositor dependency direction
  run: |
    if grep -r '"github.com/gogpu/gogpu"' internal/compositor/; then
      echo "compositor must not import root package"
      exit 1
    fi

4. Performance is not a reason to avoid extraction. We benchmarked interface calls: ~1.4-3.0ns vs ~1.3ns for direct calls. At 10 calls/frame × 60fps = ~60ns per frame vs ~16.7ms budget. 0.0005% overhead. Go 1.20+ devirtualizes most of these anyway.

What We Learned

"We'll fix it later" has a deadline you don't control. We suspected the compositor was in the wrong place for months. The deadline to fix it wasn't set by us — it was set by the overlay freeze bug and the 3D renderer needing damage tracking. Under pressure, every refactoring is harder.

Enterprise references agree on ownership. We checked Chromium, Flutter, and GTK4. In all three, the compositor owns the surface and content cache. The drawing library just draws. This isn't a coincidence — it's the architecture that survives multi-renderer apps.

Not everything needs a god struct. The Go stdlib ssa.Func pattern (single struct, 40+ fields, callback interface) is powerful but not universal. Our compositor worked better as a set of focused types (3-8 fields each) that the root package composes. Each type has a clear responsibility.

internal/ is underrated. Most Go projects either put everything in one package or create deep hierarchies. internal/ gives you encapsulation without the API commitment. The compositor is free to change its struct layout without breaking external consumers.

The Ecosystem

GoGPU is 1.25M lines of Pure Go — a full GPU ecosystem, not just one library:

Project	LOC	What it does
naga	324K	Shader compiler (WGSL → SPIR-V/MSL/GLSL/HLSL/DXIL)
gg	312K	2D graphics (Skia-class rasterizer, GPU SDF, ClearType)
wgpu	254K	WebGPU (Vulkan/DX12/Metal/GLES/Software/Browser)
ui	211K	GUI toolkit (27 widgets, 4 design systems)
gogpu	96K	App framework + compositor
g3d	14K	3D rendering (scene graph, PBR, forward renderer)
compose	10K	Multi-process composition (Unix socket, LZ4, hot-plug)
systray	8K	System tray (Win32/macOS/Linux, zero CGO)
audio	3.5K	Audio engine (WASAPI, WAV, Mixer)

Zero CGO. go build and it works. Windows, macOS, Linux, Browser.

1,200+ GitHub stars. Listed in awesome-go. Used by Born ML for GPU compute, ironwail-go for Quake 1 rendering.

The compositor migration landed across three releases: v0.51.0 (ADR-065 + ADR-066, damage source reimplementation + pluggable overlays), v0.52.0 (ADR-067, compositor-owned render target), and v0.52.1 (ADR-069, package extraction).

If your drawing library owns compositor state and you only have one consumer — fix it now. The second consumer always arrives sooner than you expect.

Try It, Break It, Tell Us

GoGPU is pre-v1.0 — this is the best time to influence the API before it freezes. We need your help:

Test on your hardware. We develop on Intel Iris Xe (Windows) and Mesa llvmpipe (Linux). AMD, NVIDIA, Apple Silicon, Adreno — every GPU we haven't tested is a bug we haven't found. Run the examples, file issues.
Contribute. PRs welcome — from typo fixes to new backends. We review everything. Check good first issues across the org.
Write about it. Tutorials, reviews, comparisons — in any language. Pavel Tišnovský wrote three parts on root.cz (Czech), covering gg 2D graphics and gogpu windowing with 12 interactive examples. If you write something, let us know — we'll link it.
Spread the word. Star us, mention us in your talks, recommend us when someone asks "how do I do GPU in Go?"

Support the Project

GoGPU is built by a small team in their spare time. If you find it useful, consider supporting continued development:

Support GoGPU on Open Collective — every contribution helps us spend more time on the ecosystem instead of client work.

Star us on GitHub: github.com/gogpu/gogpu ⭐

We Built a Pure Go 3D Renderer — Then Embedded It Inside a GUI Widget

Andrey Kolkov — Sun, 02 Aug 2026 21:33:11 +0000

Go has had a 2D graphics story for a while now. But 3D? The options have been either CGO wrappers around OpenGL, abandoned projects from 2019, or "use Ebiten and write your own engine."

We decided to build the missing piece: g3d — a Pure Go 3D rendering library with scene graph, PBR materials, and forward rendering pipeline. Zero CGO, all five GPU backends (Vulkan, Metal, DX12, GLES, Software), 374 tests, built on our WebGPU implementation.

But a 3D renderer that only works standalone is half the story. The real question is: how does it compose with UI?

This post covers the two integration patterns we shipped in v0.1.4 — patterns that every enterprise 3D application uses, from Unity to Blender to CAD tools. And how we filed eight cross-repo issues across five repositories to make it work.

The 20-Line Rotating Cube

Before we get to integration — here's what g3d looks like standalone:

scene := g3d.NewScene()
scene.SetBackground(g3d.RGB(0.1, 0.1, 0.15))

sun := g3d.NewDirectionalLight(
    g3d.WithLightColor(g3d.White),
    g3d.WithLightIntensity(1.0),
)
scene.Add(sun.LightNode())

cube := g3d.NewMesh(
    g3d.NewBoxGeometry(1, 1, 1),
    g3d.NewStandardMaterial(
        g3d.WithColor(g3d.RGB(0.4, 0.7, 1.0)),
        g3d.WithRoughness(0.6),
    ),
)
scene.Add(cube.MeshNode())

camera := g3d.NewPerspectiveCamera(75, 800.0/600.0, 0.1, 1000)
camera.CameraNode().SetPosition(g3d.Vec3{X: 0, Y: 0.5, Z: 3})

Scene graph, PBR materials, directional lighting — all CPU data structures. No GPU device needed until you render. The API is inspired by Three.js, but idiomatic Go: interfaces + functional options, not OOP inheritance chains.

The renderer creates itself lazily on first frame:

app.OnDraw(func(dc *gogpu.Context) {
    if renderer == nil {
        renderer, _ = g3d.NewRenderer(app.GPUContextProvider())
    }
    renderer.Render(scene, camera, dc.SurfaceView())
})

That's it. Rotating PBR cube on Vulkan. Single binary, zero CGO, go build && ./app.

The Real Challenge: 3D + UI

A standalone 3D window is a demo. A 3D viewport inside a GUI application — that's a product. Think about what real 3D applications look like:

Game: fullscreen 3D world with health bar, minimap, crosshair overlaid
CAD tool: 3D model viewer with toolbar, property panel, status bar around it
IDE: 3D preview panel embedded alongside code editor and file tree

These are two fundamentally different composition patterns:

Pattern	3D Renders To	UI Renders To	Who Owns the Surface
Fullscreen overlay	Swapchain directly	Same swapchain (on top)	Both, sequentially
Embedded widget	Offscreen texture	Swapchain (compositor)	UI framework

We implemented both. And both required solving problems that no Go project had solved before.

Pattern 1: Fullscreen 3D + 2D Overlay

This is the game/CAD pattern. g3d renders the 3D scene to fill the entire window, then gg (our 2D graphics library) draws HUD elements on top: title, FPS counter, crosshair, status bar.

The enterprise pattern is well-established — we researched seven engines:

Engine	How They Do It
Bevy + egui	Separate render pass, `LoadOp::Load`, `depth_stencil: None`
Dear ImGui	Separate render pass, `DepthEnable=false`, alpha blending
Unity	Screen Space Overlay canvas, rendered after everything
Godot	CanvasLayer, separate from 3D viewport
Three.js	`clearDepth()` between 3D and HUD render calls

The universal answer: two render passes on the same surface. First pass clears and renders 3D with depth testing. Second pass loads the existing content and renders 2D with alpha blending, no depth.

In g3d + gogpu + gg, this looks like:

app.OnDraw(func(dc *gogpu.Context) {
    // Pass 1: g3d renders 3D scene (LoadOp::Clear + depth)
    renderer.Render(scene, camera, dc.SurfaceView())

    // Bridge: tell gogpu the surface has content
    dc.MarkExternalContent()

    // Pass 2: gg renders 2D HUD (LoadOp::Load + alpha blend)
    canvas.Draw(func(cc *gg.Context) {
        drawHUD(cc, width, height, fps)
    })
    canvas.Render(dc.RenderTarget())
})

MarkExternalContent() is the key API. It tells the gogpu framework: "someone already rendered to this surface — don't clear it." Without this call, gg's render pass would wipe the 3D scene with LoadOp::Clear. With it, gg uses LoadOp::Load and draws transparently on top.

This is the same concept as Qt's beginExternal()/endExternal(), Flutter's InlinePassContext, and Unity's Camera.DontClear.

The Result

A rotating PBR cube at 60 FPS with a full HUD overlay — title, live FPS counter, animated crosshair, status bar with backend info. All Pure Go, all on the same swapchain, zero copies.

GOGPU_GRAPHICS_API=vulkan go run ./examples/fullscreen-overlay/

Pattern 2: 3D Inside a GUI Widget

This is the CAD/IDE pattern. The 3D viewport is one widget among many — surrounded by buttons, text, panels. The UI framework owns the window; g3d renders into an offscreen GPU texture; the compositor blits it into the widget tree.

This is how Qt's QRhiWidget, Unity's RenderTexture, and Godot's SubViewport work.

In g3d + gogpu/ui:

vp := gpuview.New(
    gpuview.Size(600, 400),
    gpuview.Continuous(true),
    gpuview.OnRender(func(view gpucontext.TextureView) {
        wgpuView := (*wgpu.TextureView)(view.Pointer())
        renderer.Render(scene, camera, wgpuView)
    }),
)

The gpuview.Widget (formerly Viewport3D, renamed for universality) handles the GPU texture lifecycle. It creates an offscreen texture, passes it to your OnRender callback, and hands the result to the Layer Tree compositor for blitting into the final frame.

Your 3D renderer doesn't know or care that it's inside a widget. It receives a TextureView and renders to it — same API as fullscreen rendering.

The UI layout is standard gogpu/ui:

uiApp.SetRoot(primitives.Box(
    primitives.Text("g3d GPUView").FontSize(22).Bold(),
    vp, // 3D viewport widget
    button.New(
        button.TextOpt("Pause / Resume"),
        button.OnClick(func() { paused = !paused }),
    ),
).Padding(28).Gap(14).Rounded(12).ShadowLevel(2))

Material 3 themed card with a 3D viewport, title, and control buttons. The 3D content renders at GPU speed inside the widget while the rest of the UI renders through the standard compositor pipeline.

go run ./examples/viewport3d/

Eight Issues Across Five Repos

Getting both patterns working wasn't just API design — it was a debugging marathon across five repositories (g3d, gg, gogpu, ui, wgpu) and eight issues. Here are the three hardest:

Bug 1: MSAA Resolve Overwrites External Content

When gg renders its 2D overlay, it uses 4x MSAA for antialiased edges. The MSAA render pass writes to an intermediate texture, then resolves to the swapchain. The resolve is a full overwrite — it doesn't care what was on the swapchain before.

So even with LoadOp::Load, the MSAA intermediate texture was empty (it never contained the 3D scene), and the resolve wrote empty + HUD to the swapchain. 3D content gone.

Fix: gg v0.50.9 implemented Strategy C from Skia's playbook — render the overlay into a separate offscreen MSAA texture, resolve to a 1x intermediate with alpha, then alpha-blend composite onto the swapchain via textured quad. The 3D content survives because the swapchain is never a resolve target.

Bug 2: GPU Buffer Use-After-Free

g3d's renderer created uniform buffers per frame with MappedAtCreation, used them in a render pass, submitted the command buffer, and immediately released them via defer. But queue.Submit() is asynchronous — the GPU was still reading the buffers when Go freed them.

command buffer at index 0 references released buffer "g3d_frame_uniforms"

Fix: Replaced per-frame allocation with persistent uniform buffers updated via queue.WriteBuffer(). Geometry buffers cached by identity. Bind groups deferred-released at the start of the next frame. This is the same pattern gg uses internally — zero allocations in the hot path.

Bug 3: Layer Tree Missing External Texture Node

The gpuview widget created its texture, fired OnRender, and g3d rendered into it correctly. But the widget was invisible. The Layer Tree compositor had ExternalTextureLayer support in its rendering code — but nobody created those nodes.

buildBoundaryLayer() only created PictureLayer nodes. Widgets with external GPU textures needed a parallel ExternalTextureLayer node so the compositor would blit their content.

Fix: ui v0.1.49 added externalTextureWidget interface detection in the Layer Tree builder. Widgets that provide Texture() and ViewportSize() automatically get an ExternalTextureLayer alongside their PictureLayer.

Shared Command Encoder: The Third Way

Sometimes you don't want two separate queue.Submit() calls. g3d v0.1.3 added RenderTo() — record g3d render passes into a caller-owned command encoder:

encoder, _ := device.CreateCommandEncoder(nil)

// g3d records its render pass
renderer.RenderTo(encoder, scene, camera, targetView)

// Other renderers record their passes
overlayRenderer.RecordTo(encoder, ...)

// One submit for the entire frame
commands, _ := encoder.Finish()
queue.Submit(commands)

This eliminates the multi-submit overhead and gives you precise control over render pass ordering. It's the pattern gogpu v0.48.4 uses internally via dc.CommandEncoder().

The Architecture

Here's how g3d fits into the gogpu ecosystem:

Your Application
    ├── gogpu (window + GPU device)
    ├── g3d  (3D scene → render passes)
    ├── gg   (2D graphics → render passes)
    └── ui   (widget tree → compositor → render passes)
              └── gpuview widget ← g3d renders here

g3d depends down only — on wgpu and gpucontext. Never on gogpu, gg, or ui. This means you can use g3d in any context: with gogpu, with your own windowing, or headless for testing.

The shared GPU device comes through gpucontext.DeviceProvider — the same database/sql-style interface pattern that gg, ui, and Born ML use. One device, shared across all renderers, zero-copy resource sharing.

The Ecosystem Is Accelerating

g3d doesn't exist in isolation. The gogpu ecosystem is growing in directions that directly benefit 3D applications:

Zero-CGO Android. @besmpl proved that CGO_ENABLED=0 -buildmode=c-shared works on Android arm64 via //go:nativeexport — a Go toolchain patch that eliminates the last CGO dependency for mobile GPU apps. The prototype runs on API 30 emulator. Once upstream, g3d will run on Android with the same go build simplicity as desktop.

Pure Go Race Detector. The GoGPU ecosystem can't use go test -race today because GPU backends require CGO_ENABLED=0. We're contributing to a Pure Go race detector that achieves read-path parity with TSAN (0.985x on Apple M1). @besmpl delivered 20 optimization commits in 5 days. When merged, every GPU-accelerated Go project gets race detection for free.

Browser/WASM. wgpu's triple-backend architecture (ADR-038) means g3d will run in the browser via WebGPU — same Go code, GOOS=js GOARCH=wasm go build. The browser backend is already shipping in wgpu for 2D; 3D follows the same path.

Composition library. gogpu/compose enables multi-process GPU composition — think VS Code's renderer process architecture, but for Go. A g3d viewport in one process, a 2D editor in another, composited via Unix socket + LZ4.

Community tutorials. Pavel Tišnovský (2,185+ articles on root.cz, Czech Republic) published 88 minutes of tutorial content covering the ecosystem with 54 working examples — the first serious European press coverage of Go GPU graphics.

Games are happening. @kivutar built Goro — a Ragnarok Online client using gogpu/ui in Pure Go (no CGO), with working UI, mercenaries, and gameplay. @darkliquid's Quake 1 port runs on our Vulkan stack. The Go game dev community is real — and it needs a 3D library that doesn't require CGO.

By the Numbers

Metric	Value
g3d LOC	~11,700
Tests	374
GPU backends	5 (Vulkan, Metal, DX12, GLES, Software)
Examples	3 (hello-cube, fullscreen-overlay, viewport3d)
Cross-repo bugs found	8
Cross-repo bugs fixed	8
Releases	3 (v0.1.2 → v0.1.4, Jul 26 – Aug 2)
Ecosystem total	1.2M+ LOC Pure Go

Try It

# Standalone 3D
go run github.com/gogpu/g3d/examples/hello-cube@latest

# Fullscreen 3D + 2D overlay
go run github.com/gogpu/g3d/examples/fullscreen-overlay@latest

# 3D inside UI widget
go run github.com/gogpu/g3d/examples/viewport3d@latest

Select your GPU backend:

GOGPU_GRAPHICS_API=vulkan   go run ./examples/hello-cube/
GOGPU_GRAPHICS_API=dx12     go run ./examples/hello-cube/
GOGPU_GRAPHICS_API=software go run ./examples/hello-cube/

What's Next

g3d v0.1.4 has the foundation: scene graph, PBR materials, forward renderer, and two production-ready integration patterns. Here's what's coming:

Phase 2 — Real Materials. Cook-Torrance BRDF replaces Blinn-Phong. Shadow mapping (directional + point). Normal maps, metallic/roughness textures, emissive maps. This is where g3d goes from "demo-ready" to "product-ready."

Phase 3 — GLTF 2.0. Binary .glb and JSON .gltf loading with PBR materials, skeletal animation, and morph targets. GLTF is the "JPEG of 3D" — every modeling tool exports it, every engine imports it. g3d will too.

Phase 4 — Scale. Instance batching for thousands of objects. Environment maps for reflections. Post-processing pipeline (bloom, tone mapping, FXAA). Skybox.

Phase 5 — Performance. BVH-accelerated frustum culling, LOD (level of detail), SIMD math via Go 1.25+ goexperiment.simd. The GoMLX PackGEMM team proved 14x speedup with Pure Go AVX-512 — same approach applies to matrix math.

The rendering library was the last missing piece in Go's graphics ecosystem. 2D graphics, GUI toolkit, shader compiler, audio engine, system tray — all Pure Go, all shipping. Now 3D joins them.

How You Can Help

This project grows through real-world usage. Every bug report from a different GPU, every feature request from a real application, every "it works on my AMD/NVIDIA/Apple M4" — that's data we can't generate alone.

Test it on your hardware. We develop on Intel Iris Xe. AMD, NVIDIA, Apple Silicon, Adreno — we need your GPU. A simple go run ./examples/hello-cube/ and a one-line issue "works on RTX 4080 / Vulkan" is genuinely valuable.

Build something with it. A 3D file viewer. A data visualizer. A game prototype. A CAD preview panel. The API is designed to be embedded — g3d doesn't own your application, you own g3d. The integration patterns in this article work today.

Report what's missing. We're tracking Phase 2–5 features, but priority depends on what people actually need. Shadows? GLTF? Instance batching? Textures? Tell us.

Spread the word. Star the repos, share the examples, write about your experience. Go's graphics ecosystem has been invisible for 17 years because nobody knew it existed. That changes when the community talks about it.

Contribute code. The CONTRIBUTING.md has everything you need. Good first issues are labeled. We review PRs within 24 hours. Every contributor gets credit in the CHANGELOG and release notes.

Support the project. We accept donations via Open Collective to fund development, testing on diverse GPU hardware, and CI infrastructure. Every contribution helps us test on more platforms and ship faster.

The ecosystem is 1.2M+ lines of Pure Go — but the codebase isn't what makes it real. Users make it real. Applications make it real. The more people building on g3d, the faster it reaches the quality bar that Go deserves.

gogpu/compose: Multi-Process GUI Composition in Pure Go

Andrey Kolkov — Sun, 17 May 2026 10:07:38 +0000

A Raspberry Pi displays a smart mirror. Clock in the top corner. Weather below. Notifications slide in from the bottom. Each panel is a separate process — if weather crashes, the clock keeps ticking.

This is gogpu/compose: a Pure Go library that lets independent processes render UI into offscreen buffers and ship pixels to a single compositor over Unix sockets.

go get github.com/gogpu/compose

The Problem

Desktop applications are monolithic. One process, one crash domain. A bug in the notification panel takes down the entire display.

Wayland solved this at the OS level — every application is a separate client, and the compositor (KWin, Mutter, Sway) combines their surfaces. Android SurfaceFlinger does the same thing for mobile apps.

But what if you need this pattern inside your application? A dashboard where each data source is an independent process. A kiosk where third-party modules render into slots. A plugin host where untrusted code runs in its own crash domain.

There was no Go library for this. You had to roll your own socket protocol, frame encoding, connection management, flow control. Every project reinvented the same plumbing.

What We Built

compose is a two-sided library: a Server (compositor) accepts connections, a Client (module) publishes frames. One import, one socket path.

Module side

client, _ := compose.Dial("/tmp/compose.sock",
    compose.WithName("clock"),
    compose.WithFrameSize(400, 120),
    compose.WithFPS(1),
)
defer client.Close()

client.OnFrameRequest(func() {
    dc := gg.NewContext(400, 120)
    dc.SetRGB(1, 1, 1)
    dc.DrawString(time.Now().Format("15:04:05"), 20, 60)

    client.PublishFrame(compose.Frame{
        Pixels: dc.ImageRGBA().Pix,
        Width:  400,
        Height: 120,
    })
})

Compositor side

srv, _ := compose.Listen("/tmp/compose.sock",
    compose.WithMaxModules(8),
    compose.WithCompression("lz4"),
)

srv.OnFrame(func(f compose.Frame) {
    layout.Place(f.Name, f.Pixels)
})

srv.OnConnect(func(id uint64, name string) {
    log.Printf("module connected: %s", name)
})

srv.OnDisconnect(func(id uint64, name string) {
    log.Printf("module gone: %s", name)
})

That's it. The module renders into a pixel buffer, publishes it. The compositor receives frames, positions them on screen. Hot-plug is automatic — modules come and go without restarting the compositor.

The Wire Protocol

Every frame travels as a 64-byte header followed by pixel data.

┌──────────────────────────────────────────────────────────┐
│ Magic "COMP" │ Version │ MsgType │ Flags                 │
│ ModuleID     │ Sequence              │ Timestamp         │
│ Width │ Height │ Stride  │ DirtyRect (x,y,w,h)           │
│ PixelFormat │ Compression │ PayloadSize │ Uncompressed   │
└──────────────────────────────────────────────────────────┘
64 bytes, little-endian, cache-line aligned

The header is fixed-size — one io.ReadFull call parses it. No variable-length fields, no schema negotiation mid-stream. Encode and decode take under 10 ns and under 25 ns respectively, with zero allocations.

The protocol carries dirty rectangles (only the changed region's pixels), compression flags, and monotonic sequence numbers for frame ordering.

Handshake

When a module connects, it sends a 128-byte HelloMsg (name, dimensions, preferred FPS). The compositor replies with a 128-byte WelcomeMsg (assigned module ID, granted transport). Fixed-size messages — no JSON parsing, no protobuf dependency, no allocation.

LZ4 Compression

GUI pixels compress exceptionally well. Buttons, backgrounds, text labels — large flat-color regions that LZ4 handles at near-memcpy speed.

Frame Size	Encode	Decode	Ratio
400×120 (small module)	2,753 MB/s	1,175 MB/s	99.6% savings
1920×1080 (full HD)	2,728 MB/s	1,446 MB/s	varies

A 192 KB module frame compresses to ~810 bytes. At 60 FPS, that's 47 KB/s over the socket — trivial for any transport.

Compression is optional. Static modules (clock, weather) benefit most. Animated modules with random pixel patterns can disable it with a flag in the frame header.

Frame Delivery: Push, Pull, and Mailbox

We researched how 9 production compositors handle frame delivery — Wayland, Android SurfaceFlinger, Chromium viz, Flutter, PipeWire, Windows DWM, macOS Core Animation, Vulkan, and X11. They all converge on the same pattern: producers submit whenever ready, the compositor samples the latest frame at its own cadence. "Push vs pull" is a false dichotomy.

compose supports both, with no mode negotiation:

Push — module sends frames whenever data changes:

// Stock ticker: push on every price update
for price := range ticker {
    client.PublishFrame(renderPrice(price))
}

Pull — module renders only when the compositor asks:

// Clock: render on demand (Wayland frame callback pattern)
client.OnFrameRequest(func() {
    client.PublishFrame(renderClock())
})

Mailbox — the compositor samples latest frames on each render tick:

// Compositor render loop: always gets the latest frame from each module
frames := srv.Snapshot()
for id, frame := range frames {
    compositor.Blit(id, frame)
}

Each module has a mailbox slot. When a module pushes faster than the compositor renders, intermediate frames are silently overwritten — latest always wins. This is the same pattern as Android's acquireLatestBuffer() and Vulkan's VK_PRESENT_MODE_MAILBOX_KHR. No stale frame accumulation, no FIFO backlog.

The adaptive flow controller still works for pull-mode modules: after 3 consecutive missed responses, it halves the request rate. Push modules bypass it entirely — the mailbox handles everything.

Architecture: Enterprise internal/

The public API has fewer than 15 exported declarations — 5 types, 2 constructors, 5 option functions, and a handful of sentinel errors. Everything else is hidden behind internal/ packages:

compose/                        # Public: Listen, Dial, Frame, options
├── internal/protocol/          # Wire format (100% coverage)
├── internal/codec/             # Raw + LZ4 (97% coverage)
├── internal/conn/              # Module lifecycle (98.9% coverage)
├── internal/flow/              # Pull-based pacing (100% coverage)
└── internal/transport/socket/  # Unix sockets (95.1% coverage)

The dependency graph is a clean DAG — protocol is the leaf (imported by all, imports nothing), codec/conn/flow are independent, transport/socket imports only protocol. No cycles possible by construction.

This isn't an accident. We designed compose the way database/sql is designed: public Server/Client wrap internal implementations. Users never import sub-packages. Adding a shared memory transport (Phase 2) won't change the public API — it's a new internal/transport/shm/ behind an existing WithSharedMemory() option.

By the Numbers

Metric	Value
Source code	2,960 LOC
Test code	6,066 LOC
Total	9,026 LOC
Test cases	179
Packages	6
Files	38
Coverage (internal avg)	98%
Header encode	< 10 ns, 0 allocs
Header decode	< 25 ns, 0 allocs
LZ4 encode throughput	2.7+ GB/s
Socket throughput	5.9+ GB/s
Dependencies	1 (`pierrec/lz4/v4`)
CGO	Zero
CI	Ubuntu + macOS + Windows
Lint (30+ rules)	0 issues

2× more test code than source code. Every internal package is independently testable with its own benchmark suite.

Who Needs This

Smart mirrors and kiosks. Independent modules (time, weather, transit, notifications) render into slots. A crash in one module doesn't affect the display.

Modular dashboards. Each data source is its own process, possibly developed by different teams. The compositor arranges them on screen.

Plugin hosts. Third-party plugins run in separate processes. The host application composites their output without trusting their code. f4 by @unxed — a full Go reimplementation of Far Manager — already uses --gui=gogpu for GPU-accelerated rendering and has an out-of-process plugin architecture (MessagePack RPC supporting Go, Python, Rust, Node.js, C++, Lua). compose could serve as the pixel transport between f4's plugin host and its GUI modules.

Cross-language UIs. The wire protocol is language-agnostic. A Rust module or a Python script can participate — anything that writes RGBA to a Unix socket.

KiGo by @AgentNemo00 — a modular Go application — is already using offscreen rendering with multi-process composition. His feedback on v0.1.0 directly shaped the mailbox delivery model in v0.2.0: he told us he uses push, we researched 9 compositors, and shipped Snapshot() two days later.

These aren't hypothetical users waiting for a stable release. They're building real software on the GoGPU stack right now — and finding real bugs that make the ecosystem better. Every project that adopts GoGPU accelerates the path to enterprise grade. If you have a desktop app, a dashboard, a kiosk, a file manager, an IDE panel — there's never been a better time to try it in Pure Go.

What's Next

Phase 2: Reference examples. Three separate binaries — compositor, clock module, notification module — demonstrating the full multi-process workflow.

Phase 3: Shared memory transport. Triple-buffer ring in mmap'd memory with atomic slot states. Zero-copy pixel transfer for 60 FPS at 1080p. The public API stays the same — you just pass WithSharedMemory().

Phase 4: Delta frames. Send only the dirty rectangle's pixels, not the full frame. The protocol already carries dirty rects in the header — we just need the compositor-side texture cache.

Try It

go get github.com/gogpu/compose

GitHub: github.com/gogpu/compose
Architecture: docs/ARCHITECTURE.md
GoDoc: pkg.go.dev/github.com/gogpu/compose
Discussion: RFC #177

Part of the GoGPU Ecosystem

compose is the newest member of GoGPU — 800K+ lines of Pure Go GPU computing:

Library	Purpose
wgpu	Pure Go WebGPU (Vulkan/Metal/DX12/GLES)
naga	Shader compiler (WGSL → SPIR-V/MSL/GLSL/HLSL/DXIL)
gg	2D graphics with GPU acceleration
ui	Enterprise GUI toolkit (22+ widgets, 4 themes)
gogpu	Application framework, windowing
compose	Multi-process composition (this library)
systray	System tray (Win32/macOS/Linux)
audio	Pure Go audio engine

Help Us Get to Enterprise Grade

The ecosystem grows faster with every pair of eyes on it. Here's how you can help:

Test it. Run go get github.com/gogpu/compose, build a two-process prototype, tell us what breaks. Edge cases on your OS, your hardware, your use case — that's what we can't find ourselves.
Validate the API. Does Listen/Dial/PublishFrame feel right? Is the wire protocol missing a field you need? The API is still v0.x — now is the time to reshape it, before it freezes.
Propose and discuss. Open an issue or join the compose RFC discussion. Real use cases drive the roadmap — not hypotheticals.
Spread the word. Star the repo, share this article, mention it in your Go meetup. The more developers use the ecosystem, the faster it reaches enterprise grade.
Contribute. Every PR matters — from typo fixes to new transport implementations. See CONTRIBUTING.md.

The entire GoGPU ecosystem — 800K+ lines of Pure Go — is built by a small team. But the libraries are production-ready enough that people are building real products on them: a Far Manager rewrite with GPU rendering, an ML framework fully migrated to our WebGPU stack, a Quake 1 engine port running on gogpu/wgpu Vulkan (demo), modular app platforms. The more developers who start building on GoGPU — whether it's a new project or porting an existing one — the faster the entire ecosystem matures. Your project's edge cases become our test suite. Your feature requests become our roadmap.

Start building. We'll make sure the foundation holds.

Building what Go "can't do." One library at a time.

gogpu/ui v0.1.21: Enterprise Render Pipeline — Layer Tree, Damage Tracking, 0% GPU Idle

Andrey Kolkov — Tue, 12 May 2026 10:23:08 +0000

Two months ago we released gogpu/ui v0.1.0 — 22 widgets, 3 design systems, ~150K lines of pure Go. Since then we shipped 21 patch releases, and the rendering pipeline is unrecognizable.

This post covers what changed and why it matters.

The Problem

v0.1.0 re-rendered the entire widget tree every frame. A 48×48 spinner in one corner caused the GPU to redraw 800×600 of static content. Hover over a button? Full tree walk. Open a dropdown? Full tree walk. This was fine for demos, not for production.

We studied how five frameworks solve this — Flutter, Chrome, Qt6, Android HWUI, Skia — and found the same architecture everywhere: Layer Tree + boundary isolation + damage tracking.

What We Built (v0.1.14 → v0.1.21)

Layer Tree Compositor

Every RepaintBoundary widget now owns a node in a persistent Layer Tree:

OffsetLayer (root)
├── PictureLayer (toolbar — clean, reuse texture)
├── PictureLayer (sidebar — clean, reuse texture)
├── ClipRectLayer (scrollview viewport)
│   └── PictureLayer (content — dirty, re-record)
└── PictureLayer (spinner — dirty, re-record 48×48)

Four layer types — OffsetLayer, PictureLayer, ClipRectLayer, OpacityLayer — compose the frame. Clean layers reuse their GPU texture from the previous frame. Only dirty layers re-render.

This is the same pattern Flutter calls flushPaint + compositeFrame. We validated it against all five reference frameworks before writing a line of code.

0% GPU When Idle

The frame loop checks a flat dirty set — O(1), not O(n) tree walk:

if !w.HasDirtyBoundaries() && !w.NeedsRedraw() && !w.NeedsAnimationFrame() {
    return // nothing changed, skip frame entirely
}

When the UI is idle, the GPU does zero work. Measured: 0% GPU across all six examples (hello, signals, taskmanager, gallery, ide, modular-compositor).

Previous approach walked the entire widget tree every frame to check if anything needed redraw. For 200 boundaries, the new approach is 45× faster.

Per-Boundary GPU Textures

Each RepaintBoundary renders into its own offscreen MSAA texture. When a child boundary becomes dirty, only that boundary's texture is re-rendered. The compositor blits all textures in a single non-MSAA pass.

A 48×48 spinner touching 2,304 pixels no longer forces the GPU to process 480,000 pixels of unchanged content.

Multi-Rect Damage

When multiple widgets are dirty in different screen regions, we don't union them into one giant rect. Each dirty rect gets its own GPU scissor:

Frame N: spinner (48×48) + status bar (800×24)
→ Two scissor rects, not one 800×600 rect
→ Zero pixel waste

The damage pipeline flows through the full stack: ui → gg RenderDirectWithDamageRects → wgpu PresentWithDamage. Ring buffer stores rect lists for N-buffer swapchains. Threshold at 16 rects merges to union (GDK/Sway pattern).

Persistent Layer Tree

UpdateLayerTree() reuses layer objects across frames instead of rebuilding the tree:

Metric	Before	After
Allocs per frame (200 boundaries)	613	13
Reduction	—	97.9%

Flutter calls this addRetained. Android calls it RenderNode reuse. We measured allocation profiles against both and matched their patterns.

The Numbers

Metric	v0.1.0	v0.1.21
Lines (total / code)	150K / 105K	195K / 141K
Tests	6,000	7,200+
Coverage	97%	97%+
Packages	56	56
GPU idle (static UI)	5-18%	0%
Frame skip check	O(n) tree walk	O(1) flat set
Allocs/frame (200 boundaries)	613	13
Spinner GPU work	full window	48×48 scissor

Ecosystem Update

The rendering pipeline required changes across four repositories. Here's where the ecosystem stands:

Repository	Version	Lines	Code	What It Does
naga	v0.17.13	323K	240K	Shader compiler: WGSL → SPIR-V, MSL, GLSL, HLSL, DXIL
gg	v0.46.8	240K	171K	2D graphics: Skia-class rasterizer, GPU SDF, scene compositor
wgpu	v0.27.3	211K	164K	Pure Go WebGPU: Vulkan, DX12, Metal, GLES, Software
ui	v0.1.21	195K	141K	GUI toolkit: 22 widgets, 4 themes, Layer Tree pipeline
gogpu	v0.34.3	61K	45K	App framework: windowing, input, three-mode render loop
+ gpucontext, gputypes, systray, audio	—	19K	13K	Shared interfaces, system tray, audio engine
Total		1,049K	774K	3,140 files across 9 repositories

1M+ total lines. 774K lines of code. Zero CGO. Zero Rust. Zero C.

Recent ecosystem highlights since the v0.1.0 article:

First Pure Go DXIL generator — naga compiles WGSL shaders directly to DXIL bytecode, eliminating the HLSL→FXC/DXC dependency. 161/170 IDxcValidator pass rate. Article.
Born ML v0.8.0 migrated to gogpu/wgpu — production ML framework running on our GPU stack. 105 GPU tests pass, HRM model trained 20 epochs. Article.
CJK text rendering — script-aware hinting, exact-size rasterization, Tier 6 routing for Chinese/Japanese/Korean glyphs.
LCD ClearType auto-detection — Windows SPI + registry, macOS None, Linux Xft/Wayland. Per-platform subpixel layout.
Software backend for CI — deterministic GPU without GPU hardware. Pixel-exact e2e tests prove scissor rects at HAL level.
Community deep-dive — independent technical analysis of gogpu/wgpu (Chinese) covering the zero-CGO syscall architecture, Snatchable resource lifecycle, and buffer state tracking internals. Always good to see the community dig into the implementation.

The Foundation Is Ready

This is the release where we stopped rebuilding and started building on top.

For the past two months every release was infrastructure: retained-mode rendering, scene composition, Layer Tree, damage tracking, boundary isolation. The kind of plumbing that's invisible to users but determines whether a framework can scale to real applications.

That plumbing is now in place. The render pipeline follows the same architectural patterns as Flutter, Chrome, and Qt6 — not because we copied them, but because we studied all five independently and arrived at the same conclusions. Layer Tree composition, per-boundary GPU textures, multi-rect damage, persistent allocation — these are industry-proven patterns, and they're production-ready in gogpu/ui.

The ecosystem has stabilized around this architecture. naga (shader compiler), wgpu (WebGPU HAL), gg (2D graphics), and gogpu (windowing) all reached the point where API churn is minimal and releases are incremental improvements, not rewrites. Nine repositories, 1M+ lines, and the dependency chain holds.

What this means going forward: the pipeline will be optimized, not rebuilt. Future releases will focus on:

New widgets — the 22 we ship today cover most use cases, but enterprise apps need more (color picker, date picker, rich text editor, tree grid)
Performance polish — reducing GPU usage for animated widgets from 10% to <3%, ListView recycling, texture GC
Platform accessibility — UIA on Windows, AT-SPI2 on Linux, NSAccessibility on macOS
Developer experience — better docs, more examples, smoother onboarding

The hard part is behind us. The interesting part is ahead.

Try It

git clone https://github.com/gogpu/ui.git
cd ui/examples/gallery
go run .

Four design systems ship out of the box: Material Design 3, JetBrains DevTools, Microsoft Fluent, Apple Cupertino. Switch between them at runtime in the gallery example.

Backend selection via environment variable:

GOGPU_GRAPHICS_API=vulkan   go run ./examples/ide/
GOGPU_GRAPHICS_API=dx12     go run ./examples/ide/
GOGPU_GRAPHICS_API=gles     go run ./examples/ide/
GOGPU_GRAPHICS_API=software go run ./examples/ide/

No code changes needed.

Help Us Get There

gogpu/ui is at the stage where the architecture is proven but the user base is small. We need real-world testing to catch edge cases that no amount of 97% coverage will find.

Test it. Clone a repo, run an example, try building something with it. If it breaks — that's valuable. File an issue, and we'll fix it. If it works — that's valuable too. Tell us what you built.

Spread the word. Most Go developers don't know this exists yet. A post on Reddit, a tweet, a mention in your team's Slack — it all helps. The project grows through people who try it and talk about it, not through marketing.

Write about it. Tutorials, experience reports, comparisons, critiques — all welcome. If you build something interesting with gogpu/ui, write about the process. The ecosystem needs content from people other than us.

Contribute. You don't need to touch the render pipeline. Documentation improvements, new examples, widget ideas, accessibility testing, CI on different hardware — there's work at every level. Check CONTRIBUTING.md or just open a discussion.

The codebase is 1M+ lines of pure Go with zero CGO. The foundation is solid. What it needs now is people building on it.

GitHub · Discussions · CHANGELOG · Reddit r/golang · X/Twitter

DEV Community: GoGPU

A Shader Loop That Never Ran: What GPU Readback Found in gogpu/naga, a Go WGSL Compiler

What the validator saw

What naga is

Running the output instead

What it caught

When Rust naga and the spec disagree

What I'd do differently

What's next

gogpu/ui v0.1.54: We Built Flutter's Gesture System in Pure Go — Arena, Recognizers, and All

The Problem: Every Widget Reinvented Click Detection

What We Built

The Gesture Arena

Four Recognizers + VelocityTracker

Per-Device Thresholds

Unified Pointer Pipeline

Container Widget Hit-Testing

TextField: The Full Story

OS Clipboard

Signals Integration

Numbers

What's Next

Help Us Build Go's GUI Future

GoGPU: Extracting a GPU Compositor in Pure Go — Patterns from Flutter and Chromium

The Setup: a Compositor Hidden Inside a Drawing Library

The Breaking Point: Three Problems, One Root Cause

Problem 1: Damage rects were single-source

Problem 2: Two overlays, two libraries

Problem 3: The move that broke everything

Phase 1: Moving the Compositor Out of gg (ADR-067)

Phase 2: Extracting internal/compositor/ (ADR-069)

Research first

What we actually built

The numbers

Rules That Emerged

What We Learned

The Ecosystem

Try It, Break It, Tell Us

Support the Project

We Built a Pure Go 3D Renderer — Then Embedded It Inside a GUI Widget

The 20-Line Rotating Cube

The Real Challenge: 3D + UI

Pattern 1: Fullscreen 3D + 2D Overlay

The Result

Pattern 2: 3D Inside a GUI Widget

Eight Issues Across Five Repos

Bug 1: MSAA Resolve Overwrites External Content

Bug 2: GPU Buffer Use-After-Free

Bug 3: Layer Tree Missing External Texture Node

Shared Command Encoder: The Third Way

The Architecture

The Ecosystem Is Accelerating

By the Numbers

Try It

What's Next

How You Can Help

Links

gogpu/compose: Multi-Process GUI Composition in Pure Go

The Problem

What We Built

Module side

Compositor side

The Wire Protocol

Handshake

LZ4 Compression

Frame Delivery: Push, Pull, and Mailbox

Architecture: Enterprise internal/

By the Numbers

Who Needs This

What's Next

Try It

Part of the GoGPU Ecosystem

Help Us Get to Enterprise Grade

gogpu/ui v0.1.21: Enterprise Render Pipeline — Layer Tree, Damage Tracking, 0% GPU Idle

The Problem

What We Built (v0.1.14 → v0.1.21)

Layer Tree Compositor

0% GPU When Idle

Per-Boundary GPU Textures

Multi-Rect Damage