RFC: Multi-Window Support for gogpu

[kolkov]

RFC: Multi-window architecture for gogpu

Scope: this RFC covers in-process multi-window only — one gogpu application opening N native windows that share one GPU Device, on the model of Qt6, GTK4, SDL3, and winit. It is not about multi-process composition (independent processes feeding pixels into one display); that is a separate library, gogpu/compose, and the two are orthogonal layers, not alternatives. See Out of scope for the comparison.

TL;DR

We propose adding multi-window support to gogpu so a single application can open and manage N native windows from one process. The architecture follows the unanimously-validated pattern used by every mature desktop UI framework: one shared GPU Device, one Surface per window, monotonic WindowID, centralized event loop with per-window event routing. Implementation is approximately 1500 LOC of platform code plus a renderer split, with zero breaking changes for existing single-window applications.

This RFC is the public draft of internal ADR-010. We are asking for community feedback — on API shape, window types, quit semantics, edge cases — before writing 1500 lines of platform code.

Why this matters

gogpu currently allows exactly one window per App. That is a hard ceiling on what you can build:

• IDE-style layouts — main editor + tool palette + output panel + debugger
• Multi-document applications — multiple editor windows, each its own document
• Modal and modeless dialogs — settings, file pickers, confirmation prompts
• Floating tool palettes — color pickers, asset browsers, debug overlays
• System tray applications — main window plus on-demand popup windows

Every other modern UI framework (Qt, GTK, SDL, winit, Cocoa, Win32 directly) treats multi-window as a baseline feature, not an opt-in. Until gogpu does the same, building a serious desktop application on top of it requires custom workarounds that bypass the window manager — which means no native chrome, no native window-manager integration, no native focus handling, and no native multi-monitor placement.

Research summary

Before drafting this, we read the relevant code in seven mature multi-window implementations and wrote internal research reports for each. The conclusions converge cleanly:

Source	Lessons we adopted
Qt6 (QRhi + QRhiSwapChain)	Per-window swapchain, lazy creation, SurfaceAboutToBeDestroyed lifecycle, close-as-request (window can reject), shared QRhi for resources
GTK4 (GdkDisplay + GskRenderer)	One shared VkDevice per GdkDisplay, GskGpuDevice singleton, per-surface GskRenderer, g_application_hold/release quit refcount
SDL3 (SDL_ClaimWindowForGPUDevice)	Monotonic WindowID, SetProp for native-handle-to-Window routing, event dedup for resize/move events
winit	WindowId as a stable handle, EventLoop polls all windows, per-window state in side maps keyed by ID
GLFW	GetPropW / XFindContext for native-handle routing, polling at the platform layer (process-level)
wgpu (Rust)	Arc<Device> shared across surfaces, no per-surface device, no per-window thread
Fyne / Gio (Go ecosystem)	Centralized event loop (Fyne) vs per-window goroutine + LockOSThread (Gio); we evaluated both and prefer centralized for our platform constraints

The unanimous answer across all seven projects: shared GPU device + per-window swapchain is the right architecture for desktop applications. Per-window devices are at most a v2 optimization for performance-critical workloads, never a starting point.

Proposed architecture

Shared GPU context, per-window surface

graph TD
    GPU["<b>GPUContext (shared)</b><br/>Instance / Adapter / Device<br/>Queue / Shared Pipelines<br/>Shared Textures & Buffers"]

    GPU --> W1
    GPU --> W2
    GPU --> W3

    W1["<b>Window 1</b><br/>Surface / Swapchain<br/>FrameState / Callbacks"]
    W2["<b>Window 2</b><br/>Surface / Swapchain<br/>FrameState / Callbacks"]
    W3["<b>Window 3</b><br/>Surface / Swapchain<br/>FrameState / Callbacks"]

    style GPU fill:#2d5a3d,stroke:#4a9,color:#fff
    style W1 fill:#1a3a5c,stroke:#4a9,color:#fff
    style W2 fill:#1a3a5c,stroke:#4a9,color:#fff
    style W3 fill:#1a3a5c,stroke:#4a9,color:#fff

Loading

One Instance / Adapter / Device / Queue lives in GPUContext. Each window owns its own Surface, swapchain, per-frame state, and callbacks. Pipelines and textures are shared via GPUContext — create a texture once, use it from any window.

WindowID is a monotonic uint32

type WindowID uint32 // zero is invalid; assigned by the platform on CreateWindow

var nextWindowID atomic.Uint32

func newWindowID() WindowID {
    return WindowID(nextWindowID.Add(1))
}

Why monotonic, not the native handle:

• Native handles can change on Android suspend/resume (winit lesson)
• Raw pointers are unsafe to embed in event structs (Go GC)
• Monotonic IDs are stable, serializable, and trivially small (4 bytes)
• SDL3 uses the same pattern (SDL_GetNextObjectID)

Window registry: a Go map

type WindowManager struct {
    mu      sync.RWMutex
    windows map[WindowID]*Window  // O(1) lookup
    order   []WindowID            // insertion order for deterministic iteration
    focused WindowID              // currently focused window
}

Pre-allocated to size 8 — zero allocations for ≤8 windows, which covers virtually every real desktop application. Go maps give O(1) lookup, superior to GLFW/SDL3's linked lists.

Platform interface split: PlatformManager + PlatformWindow

The current Platform interface bundles process-level concerns (event loop, clipboard, system preferences) with per-window concerns (size, title, cursor, present). For multi-window, we split it into two:

// PlatformManager — process-level, exactly one per App.
type PlatformManager interface {
    Init() error
    CreateWindow(config WindowConfig) (PlatformWindow, error)
    PollEvents() WindowEvent
    WaitEvents()
    WakeUp()
    ClipboardRead() (string, error)
    ClipboardWrite(text string) error
    SystemPreferences() SystemPrefs
    Destroy()
}

// PlatformWindow — per-window, N per App.
type PlatformWindow interface {
    ID() WindowID
    GetHandle() (instance, window uintptr)
    LogicalSize() (w, h int)
    PhysicalSize() (w, h int)
    ScaleFactor() float64
    PrepareFrame() PrepareFrameResult
    SetTitle(title string)
    SetCursor(cursorID int)
    Close()    // request — may be rejected by OnClose
    Destroy()  // releases native resources
    // ... ~23 per-window methods total
}

This mirrors Qt6's split between QPlatformIntegration and QPlatformWindow.

WindowEvent is tagged with WindowID

type WindowEvent struct {
    WindowID       WindowID
    Type           EventType
    Width          int
    Height         int
    PhysicalWidth  int
    PhysicalHeight int
}

Value type returned by value from PollEvents(). Zero allocations per event. Stale resize/move events are deduped before enqueuing (SDL3 pattern) so rapid window dragging cannot overflow the queue.

Per-window callbacks: a struct, not N setters

type WindowCallbacks struct {
    OnPointer    func(PointerEvent)
    OnScroll     func(ScrollEvent)
    OnKey        func(Key, Modifiers, bool)
    OnChar       func(rune)
    OnHitTest    func(x, y float64) HitTestResult
    OnModalFrame func()
    OnClose      func() bool  // return false to reject the close
}

Set once via SetWindowCallbacks(id, callbacks). OnClose returning bool is the close-as-request pattern from Qt6 — the application may reject a close if there is unsaved work.

Surface destruction must precede native window destruction

GPU swapchain MUST be destroyed BEFORE the native window (HWND, NSView, X11 Window). Reversing the order produces driver crashes on every backend — this is the Qt6 SurfaceAboutToBeDestroyed lesson. WindowManager enforces this by listening for EventSurfaceAboutToBeDestroyed and releasing the WindowSurface before allowing the native window to die.

VSync strategy

Sequential Present to N VSync surfaces causes N × VBlank delay. A 3-window IDE on a 60Hz display would render at 20Hz if every window used Fifo. Strategy:

• Focused window: Fifo (vsync on)
• Other windows: Immediate or Mailbox
• On focus change: swap modes accordingly

Matches Qt6 and Chromium.

Window types

type WindowType int

const (
    WindowTypeNormal  WindowType = iota  // top-level, taskbar entry
    WindowTypeDialog                     // modal/modeless, owned by parent
    WindowTypeTool                       // floating palette, no taskbar
    WindowTypePopup                      // menu, tooltip, dropdown
)

Mirrors Qt::WindowFlags, GTK's GdkToplevel/GdkPopup, and SDL3 parent/child hierarchies.

Quit logic

type QuitBehavior int

const (
    QuitOnLastPrimaryWindowClosed QuitBehavior = iota  // default
    QuitOnExplicitQuit                                 // app.Quit() only
    QuitOnLastWindowClosed                             // any window type
)

By default tool windows and popups do not participate in the "last window" count — closing them does not quit the application (Qt6 pattern). Apps can override.

Backward compatibility

Existing single-window code continues to work unchanged. NewApp(config) still creates one window automatically. App.NewWindow(config) is the new API for additional windows. Zero breaking changes.

Implementation phases

Phase	Scope	Effort
Phase 1	Internal platform refactoring (no API break): per-HWND/per-NSWindow/per-surface state, event routing	Win32 ~200, X11 ~150, Wayland ~300, macOS ~150 LOC
Phase 2	New interfaces, GPUContext/WindowSurface split, WindowManager, backward-compat wrapper	renderer ~400, app ~300 LOC
Phase 3	Multi-window frame loop, per-window callbacks, event routing, VSync strategy, close-as-request	included above
Phase 4	Window types, parent-child relationships, integration with gogpu/ui	TBD

Total estimate: ~1500 LOC across gogpu, ~100 LOC in gpucontext. No changes needed in wgpu for Vulkan / Metal / DX12 — already multi-surface ready. GLES needs ~50 LOC for MakeCurrent switching.

Out of scope

Multi-process composition (gogpu/compose)

This RFC is about one process opening many native windows. It is not about many independent processes feeding pixels into one display — that is the opposite problem, and it is being addressed by a separate library, gogpu/compose, currently in design phase.

The two are layers, not alternatives. Every row of this comparison shows a fundamental difference:

Concern	Multi-window in gogpu (this RFC)	Multi-process compose
Number of processes	1	N + 1 (modules + compositor)
GPU Devices	1, shared across all windows	N independent, one per process
Resource sharing	full — pipelines, textures, buffers	only pixels via IPC
Trust model	full trust between windows	process isolation
Crash containment	none — one window crashes, the whole process dies	strong — one module dies, the compositor and other modules live
Cross-language modules	Go only	any language with POSIX sockets (Rust, C, Python …)
Hot-reload of modules	not a goal	first-class concern
Communication cost	function call (zero)	IPC framing (small but nonzero)
Frame budget	microseconds	milliseconds
Wire protocol	none	versioned, stable compatibility surface
Authoritative use cases	IDEs with dockable panels, multi-document editors, dialogs, tool palettes	smart mirrors, kiosks, plugin hosts, modular dashboards, cross-language UIs

No row in this table is the same. They are mathematically opposite: this RFC is 1 process → N windows, while compose is N processes → 1 display.

The two stack cleanly. A compose compositor process can use multi-window from this RFC internally if it wants to span multiple physical monitors (one OS window per monitor). A compose module can use multi-window internally if it wants debug sub-windows. They compose, but they are not interchangeable: trying to make this RFC's multi-window cover the multi-process case would force every gogpu user to pay the cost of IPC and protocol versioning even for a simple dialog box; trying to make compose cover the single-process case would force an IDE to spawn a separate process per panel and pay milliseconds of latency for what should be a function call.

Per-window threads

Gio spawns a goroutine per window with runtime.LockOSThread. We evaluated this and chose centralized polling instead, because macOS forces all AppKit calls onto the main thread and GL forces MakeCurrent per thread anyway. Per-window threads do not buy enough on the platforms we support to justify the extra complexity. We may revisit for Vulkan/DX12 multi-threaded command encoding later.

Per-window devices

Qt6 recommends per-window QRhi for performance-critical workloads, but it doubles GPU memory usage and breaks resource sharing between windows. Our default for v1 is shared device. Per-window devices are a v2 conversation if and when benchmarks show shared device is a real bottleneck.

Multi-GPU presentation

All windows share one Device on one physical GPU for v1. Cross-GPU presentation is handled by the OS (Windows WDDM does this transparently with some latency). Per-GPU Devices are a v2 question if anyone has multi-monitor setups with monitors connected to different GPUs and shows a real workload that suffers from cross-GPU copies.

What we want from this discussion

Before we begin implementation, we want feedback on:

1. API shape. Is App.NewWindow(config) the right entry point, or should windows be created independently (Gio style: each window is a standalone object)? Is WindowID as uint32 the right level of typing, or should it be a struct with a name field?

2. Window types. Is Normal / Dialog / Tool / Popup complete? Do you have a use case for splash screens, child-of-parent windows, undecorated overlays, tooltips with their own lifecycle, that does not fit one of these four?

3. Quit semantics. Is QuitOnLastPrimaryWindowClosed the right default, or should we follow Qt's quitOnLastWindowClosed (any window type counts) or GTK's explicit hold/release refcount?

4. Backward compatibility constraints we missed. If you have a gogpu application today and would be affected by this work, please describe how — we want to know before shipping anything that breaks you.

5. VSync edge cases on multi-monitor. Mixed refresh rates (60Hz + 144Hz, 60Hz + ProMotion 120Hz) — does our "primary Fifo, secondary Immediate" strategy work for you, or do you need per-monitor VSync handling?

6. Anything we missed entirely. This RFC is the result of three weeks of research, but research only goes so far without real users testing the design. If you have built multi-window in Go before — in Fyne, Gio, walk, gioui, or anything else — tell us what worked and what didn't.

Status

• Research: complete (7 internal reports across gogpu/docs/dev/research/)
• ADR-010 (internal): accepted as proposed
• This RFC (public draft): open for community feedback
• Implementation: scheduled, not started

If feedback in this discussion changes the design materially, ADR-010 will be amended and the change recorded here. If feedback confirms the direction, implementation begins in the next sprint.

Thank you for reading this far. Multi-window is one of the larger architectural commitments we have made on gogpu, and we want to get the design right before writing 1500 lines of platform code.

[kolkov]

Implemented in v0.28.0

Multi-window support is now shipped in v0.28.0.

What's available

• App.NewWindow(config) -- creates additional windows with shared GPU device
• Per-window callbacks: SetOnDraw, SetOnResize, SetOnClose
• PlatformManager / PlatformWindow -- clean process/window separation
• WindowManager with monotonic WindowID (SDL3 pattern)
• Multi-window frame loop -- renders all visible windows per tick
• VSync strategy: primary window Fifo, secondary Immediate
• Verified on Win32 Vulkan (Intel Iris Xe)

Example

app := gogpu.NewApp(gogpu.DefaultConfig().
    WithTitle("Primary").WithSize(600, 400))

app.OnDraw(func(ctx *gogpu.Context) {
    ctx.Clear(0.2, 0.3, 0.8, 1.0) // Blue
})

var created bool
app.OnUpdate(func(dt float64) {
    if created { return }
    created = true
    w2, _ := app.NewWindow(gogpu.DefaultConfig().
        WithTitle("Second").WithSize(400, 300))
    w2.SetOnDraw(func(ctx *gogpu.Context) {
        ctx.Clear(0.8, 0.2, 0.3, 1.0) // Red
    })
})

app.Run()

Remaining work (separate issues)

• Window types (Dialog, Tool, Popup) with parent-child
• EventFocus for VSync switching on focus change
• Linux/macOS multi-window testing

Thank you to everyone who reviewed the RFC. The architecture followed the design proposed here with minor adjustments (removed backward-compat adapter layers in favor of direct PlatformManager usage).

Closing as implemented.