gpucontext

Shared GPU infrastructure for the gogpu ecosystem.

Overview

gpucontext provides interfaces and utilities for sharing GPU resources across multiple packages without circular dependencies.

Relationship to gputypes

Package	Purpose	Dependencies
gputypes	WebGPU types (enums, structs, constants)	ZERO
gpucontext	Interfaces (DeviceProvider, EventSource, WindowChrome, Texture)	imports gputypes

gpucontext imports gputypes to use shared types in interface signatures, ensuring type compatibility across the ecosystem.

Installation

go get github.com/gogpu/gpucontext

Requires: Go 1.25+

Features

• DeviceProvider — Interface for injecting GPU device and queue (typed, zero any)
• WindowProvider — Window geometry, DPI scale factor, and redraw requests
• PlatformProvider — Clipboard, cursor, dark mode, and accessibility preferences
• CursorShape — 12 standard cursor shapes (arrow, pointer, text, resize, etc.)
• EventSource — Interface for input events (keyboard, mouse, window, IME)
• PointerEventSource — W3C Pointer Events Level 3 (unified mouse/touch/pen)
• ScrollEventSource — Scroll/wheel events with pixel/line/page modes
• Texture — Minimal interface for GPU textures with TextureUpdater/TextureRegionUpdater/TextureDrawer/TextureCreator
• IME Support — Input Method Editor for CJK languages (Chinese, Japanese, Korean)
• WindowChrome — Custom window chrome for frameless windows (hit testing, minimize/maximize/close) + runtime fullscreen toggle
• Registry[T] — Generic registry with priority-based backend selection
• WebGPU Interfaces — Device, Queue, Adapter, Surface interfaces
• WebGPU Types — Re-exports from gputypes (TextureFormat, etc.)

Usage

DeviceProvider Pattern

The DeviceProvider interface enables dependency injection of GPU capabilities:

// In gogpu/gogpu - implements DeviceProvidertypeAppstruct {
device gpucontext.Devicequeue gpucontext.Queue
}
func (app*App) Device() gpucontext.Device { returnapp.device }
func (app*App) Queue() gpucontext.Queue { returnapp.queue }
func (app*App) SurfaceFormat() gpucontext.TextureFormat { returnapp.format }
func (app*App) Adapter() gpucontext.Adapter { returnapp.adapter }
// In gogpu/gg - uses DeviceProviderfuncNewGPUCanvas(provider gpucontext.DeviceProvider) *Canvas {
return&Canvas{
device: provider.Device(),
queue: provider.Queue(),
}
}

Device Sharing (typed, zero any)

GPU accelerators (like gg's SDF pipeline) share the host device via typed interfaces:

// Consumer gets typed device from providerfunc (a*SDFAccelerator) SetDeviceProvider(dp gpucontext.DeviceProvider) {
dev:=dp.Device() // gpucontext.Device (minimal interface)wgpuDev, ok:=dev.(*wgpu.Device) // type assert for full wgpu APIifok {
a.initWithSharedDevice(wgpuDev)
}
}

The pattern follows Go's "accept interfaces, return structs":

• gpucontext.Device — minimal interface (type token)
• *wgpu.Device — concrete type, satisfies gpucontext.Device implicitly
• Consumer type-asserts when it needs the full API

WindowProvider (for UI frameworks and rendering libraries)

The WindowProvider interface enables UI frameworks and rendering libraries to query window dimensions (logical points) and DPI scale factor:

// In gogpu/ui - uses WindowProvider for layoutfunc (ui*UI) Layout(wp gpucontext.WindowProvider) {
w, h:=wp.Size() // logical points (DIP)scale:=wp.ScaleFactor() // 2.0 on Retinaui.root.Layout(w, h, scale)
}
// In gg/ggcanvas - auto-detects HiDPI from providerfuncNew(provider gpucontext.DeviceProvider, w, hint) (*Canvas, error) {
scale:=1.0ifwp, ok:=provider.(gpucontext.WindowProvider); ok {
scale=wp.ScaleFactor()
}
// allocate pixmap at physical resolution: w*scale x h*scale
}

PlatformProvider (optional OS integration)

PlatformProvider exposes clipboard, cursor, and system preferences. Not all hosts support it — use type assertion to check:

// In gogpu/ui - cursor managementfunc (ui*UI) UpdateCursor(provider gpucontext.WindowProvider) {
ifpp, ok:=provider.(gpucontext.PlatformProvider); ok {
pp.SetCursor(gpucontext.CursorPointer) // hand cursor
}
}
// In gogpu/ui - clipboardfunc (ui*UI) Paste(provider gpucontext.WindowProvider) {
ifpp, ok:=provider.(gpucontext.PlatformProvider); ok {
text, err:=pp.ClipboardRead()
iferr==nil {
ui.focused.InsertText(text)
}
}
}
// In gogpu/ui - theme detectionfunc (ui*UI) DetectTheme(provider gpucontext.WindowProvider) {
ifpp, ok:=provider.(gpucontext.PlatformProvider); ok {
ifpp.DarkMode() {
ui.SetTheme(DarkTheme)
}
}
}

EventSource (for UI frameworks)

EventSource enables UI frameworks to receive input events from host applications:

// In gogpu/ui - uses EventSourcefunc (ui*UI) AttachEvents(source gpucontext.EventSource) {
source.OnKeyPress(func(key gpucontext.Key, mods gpucontext.Modifiers) {
ui.focused.HandleKeyDown(key, mods)
})
source.OnMousePress(func(button gpucontext.MouseButton, x, yfloat64) {
widget:=ui.hitTest(x, y)
widget.HandleMouseDown(button, x, y)
})
}
// In gogpu/gogpu - implements EventSourcetypeAppstruct {
keyHandlers []func(gpucontext.Key, gpucontext.Modifiers)
}
func (app*App) OnKeyPress(fnfunc(gpucontext.Key, gpucontext.Modifiers)) {
app.keyHandlers=append(app.keyHandlers, fn)
}

IME Support (CJK Input)

IMEState and related interfaces enable Input Method Editor support for Chinese, Japanese, and Korean input:

// In gogpu/ui - handle IME compositionfunc (input*TextInput) AttachIME(source gpucontext.EventSource) {
source.OnIMECompositionStart(func() {
input.showCompositionWindow()
})
source.OnIMECompositionUpdate(func(state gpucontext.IMEState) {
// Show composition text with cursorinput.setCompositionText(state.CompositionText, state.CursorPos)
})
source.OnIMECompositionEnd(func(committedstring) {
// Insert final textinput.insertText(committed)
input.hideCompositionWindow()
})
}
// Control IME position (for composition window placement)func (input*TextInput) Focus(controller gpucontext.IMEController) {
controller.SetIMEEnabled(true)
controller.SetIMEPosition(input.cursorX, input.cursorY)
}

Texture Interface

Texture provides a minimal interface for GPU textures, enabling sharing between packages:

// Texture is a minimal interface for GPU texturestypeTextureinterface {
Width() intHeight() int
}
// TextureDrawer can draw textures (implemented by renderers)typeTextureDrawerinterface {
DrawTexture(texTexture, x, yfloat32) errorDrawTextureEx(texTexture, optsTextureDrawOptions) error
}
// TextureCreator can create textures from pixel datatypeTextureCreatorinterface {
CreateTexture(width, heightint, pixels []byte) (Texture, error)
}

TextureUpdater (Dynamic Content)

TextureUpdater enables efficient texture updates without recreating textures:

// TextureUpdater updates existing texture pixel data (full upload)typeTextureUpdaterinterface {
UpdateData(data []byte) error
}
// TextureRegionUpdater uploads only a sub-rectangle (partial upload)typeTextureRegionUpdaterinterface {
UpdateRegion(x, y, w, hint, data []byte) error
}

TextureRegionUpdater enables incremental rendering — only dirty regions are uploaded to GPU instead of the full texture. For a 1080p@2x window, this reduces upload from ~33MB to a few KB per frame when only a small widget changes.

Usage in integration packages:

// In gg/integration/ggcanvas - creates textures from CPU canvasfunc (c*Canvas) Flush() (gpucontext.Texture, error) {
pixels:=c.pixmap.Pix()
returnc.creator.CreateTexture(c.width, c.height, pixels)
}
// In gogpu - implements TextureDrawerfunc (ctx*Context) DrawTexture(tex gpucontext.Texture, x, yfloat32) error {
returnctx.renderer.DrawTexture(tex, x, y)
}

WindowChrome (frameless windows + fullscreen)

WindowChrome enables custom window chrome for frameless windows and runtime fullscreen toggle:

// In gogpu/ui - custom title bar with hit testingfunc (ui*UI) SetupFramelessWindow(provider gpucontext.WindowProvider) {
ifwc, ok:=provider.(gpucontext.WindowChrome); ok {
wc.SetFrameless(true)
wc.SetHitTestCallback(func(x, yfloat64) gpucontext.HitTestResult {
ify<40 { // title bar heightreturngpucontext.HitTestCaption// enables window dragging
}
returngpucontext.HitTestClient
})
}
}
// Window controlswc.Minimize()
wc.Maximize() // toggles maximized/restoredwc.IsMaximized() // for button icon statewc.SetFullscreen(true) // enter fullscreen (borderless on Win, native on macOS)wc.IsFullscreen() // query fullscreen statewc.Close()

Backend Registry

The Registry[T] provides thread-safe registration with priority-based selection:

import"github.com/gogpu/gpucontext"// Create registry with priority ordervarbackends= gpucontext.NewRegistry[Backend](
gpucontext.WithPriority("vulkan", "dx12", "metal", "gles", "software"),
)
// Register backends (typically in init())funcinit() {
backends.Register("vulkan", NewVulkanBackend)
backends.Register("software", NewSoftwareBackend)
}
// Get best available backendbackend:=backends.Best()
// Or get specific backendvulkan:=backends.Get("vulkan")
// Check availabilityifbackends.Has("vulkan") {
// Vulkan is available
}
// List all availablenames:=backends.Available() // ["vulkan", "software"]

Dependency Graph

 gputypes (ZERO deps)
All WebGPU types (100+)
│
▼
gpucontext
(imports gputypes)
DeviceProvider, WindowChrome,
WindowProvider, PlatformProvider,
EventSource, Texture, Registry
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
gogpu gg ui
(implements) (uses) (uses)
│
▼
wgpu/hal

Ecosystem

Package	Description
gogpu/gogpu	Graphics framework, implements DeviceProvider
gogpu/gg	2D graphics, uses DeviceProvider
gogpu/wgpu	Pure Go WebGPU implementation
born-ml/born	ML framework, implements & uses

Star History

License

MIT License — see LICENSE for details.