README
¶
wgpu
github.com/cog-engine/wgpu is Cog's window, input, timing, and WebGPU system
driver built on gogpu. It owns the OS main loop, implements the gfx.Backend,
feeds input, and drives the app update/render contract on desktop and WebAssembly.
Plugin
- Name:
wgpu.Name("wgpu") - Constructor:
wgpu.New() *wgpu.Plugin - Plugin dependencies:
gfx,input - Go package dependencies:
app,gfx,input,kernel,gogpu, WebGPU implementation packages - Implements:
kernel.Host - Subscribed kernel events: none
Register dependencies before the driver. Run(ctx) owns the calling thread and
blocks in the platform main loop until the window closes, app.QuitCmd runs, or
the context is canceled.
Plugin implements Name, Dependencies, Init, and Run.
Configuration
Start from DefaultConfig() and use immutable setters:
cfg := wgpu.DefaultConfig().
WithTitle("My App").
WithAppName("My App").
WithSize(1280, 720).
WithResizable(true).
WithVSync(true).
WithFullscreen(false).
WithStep(time.Second / 60).
WithMaxFrame(250 * time.Millisecond).
WithMaxPending(4)
Config also exposes all fields directly: Step, MaxFrame, MaxPending,
Title, Width, Height, Resizable, VSync, Fullscreen, and AppName.
ErrInvalidConfig{Got} reports a configuration value of the wrong type and its
Error() string method implements error.
Command Implemented
app.QuitCmd calls the underlying application's Quit method. It has no
resource locks.
Commands Executed
input.ApplyCmd: flushes the frame's ordered key, pointer, scroll, and text changes into the input plugin before updates.gfx.SetViewportCmd: supplies logical-window and physical-framebuffer sizes each drawable frame.gfx.SetBackendCmd: installs the lazily created WebGPU backend once the device and surface are ready.
Events Published
app.InitEvent: published synchronously once inRun, immediately before entering gogpu's blocking main loop.app.UpdateEvent: published synchronously on the main thread at the fixedConfig.Step. Long frames are clamped byMaxFrame; at mostMaxPendingcatch-up events are emitted, and the last hasLast: true.gfx.WindowSizeChangeEvent: published synchronously when DIP window size changes, beforeSetViewportCmdresolves the viewport.app.RenderEvent: published synchronously on the render thread after the surface is current.Alphais the remaining fixed-step interpolation ratio.app.QuitEvent: published synchronously once when gogpu's main loop returns.
The driver does not subscribe through the kernel registry; gogpu callbacks
invoke its update, draw, and input bridges directly.
Backend Behavior
The private backend implements the public gfx.Backend contract. It maps Cog's
opaque IDs to native WebGPU textures and buffers, reflects WGSL bindings, caches
pipelines/samplers/bind groups, maintains depth targets, performs queued bakes
and releases, and submits each translated gfx.GpuQueue to the current surface.
Desktop and WebAssembly platform differences are hidden behind build-tagged files; the public API is identical.
Documentation
¶
Overview ¶
Package wgpu is cog's window + input + GPU driver plugin, built on gogpu. It is a kernel.PluginHost: it owns the OS main loop and drives the engine's fixed-timestep Update and per-frame Render events (declared in package app).
gogpu's OnUpdate becomes ordered fixed-timestep app.UpdateEvent values through an accumulator, and OnDraw publishes app.RenderEvent{Alpha} as a render-thread barrier. The plugin also implements gfx.Backend, forwards OS input into the input contract, and reports window and framebuffer sizes to the viewport.
Index ¶
- Constants
- type Config
- func (c Config) WithAppName(name string) Config
- func (c Config) WithFullscreen(fullscreen bool) Config
- func (c Config) WithMaxFrame(d time.Duration) Config
- func (c Config) WithMaxPending(n int) Config
- func (c Config) WithResizable(resizable bool) Config
- func (c Config) WithSize(width, height int) Config
- func (c Config) WithStep(step time.Duration) Config
- func (c Config) WithTitle(title string) Config
- func (c Config) WithVSync(vsync bool) Config
- type ErrInvalidConfig
- type Plugin
Constants ¶
const Name kernel.PluginName = "wgpu"
Name is the plugin name wgpu registers under; it is also its key in the config map passed to kernel.New.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Step is the fixed simulation interval (the update rate). Default: 1/60s.
Step time.Duration
// MaxFrame clamps the elapsed time absorbed in a single frame, bounding
// catch-up work after a stall (anti spiral-of-death). Default: 250ms.
MaxFrame time.Duration
// MaxPending bounds how many catch-up steps may queue before extras are
// dropped. Default: 4.
MaxPending int
// Title is the window title. Default: "cog".
Title string
// Width and Height are the initial logical window size (DIP). Default: 1280x720.
Width, Height int
// Resizable allows the window to be resized. Default: true.
Resizable bool
// VSync enables vertical sync. Default: true.
VSync bool
// Fullscreen starts the window fullscreen. Default: false.
Fullscreen bool
// AppName is the application/menu name (macOS). Default: empty (gogpu default).
AppName string
}
Config configures the wgpu driver. Build it from DefaultConfig and the With* setters (each returns a modified copy), mirroring gogpu's config style:
cfg := wgpu.DefaultConfig().WithTitle("Feuds").WithSize(1600, 900)
It is delivered through kernel.New's config map, keyed by Name. Fields are exported so a Config can be serialized.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns the default configuration. Chain With* setters to override.
func (Config) WithAppName ¶
WithAppName sets the application/menu name (macOS).
func (Config) WithFullscreen ¶
WithFullscreen sets whether the window starts fullscreen.
func (Config) WithMaxFrame ¶
WithMaxFrame sets the per-frame elapsed-time clamp.
func (Config) WithMaxPending ¶
WithMaxPending sets the catch-up queue capacity.
func (Config) WithResizable ¶
WithResizable sets whether the window can be resized.
type ErrInvalidConfig ¶
type ErrInvalidConfig struct {
Got any
}
ErrInvalidConfig is returned by the plugin's Register when the config value handed to it is neither nil nor a wgpu.Config.
func (ErrInvalidConfig) Error ¶
func (e ErrInvalidConfig) Error() string
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin is the wgpu driver. Hand it to kernel.New; its configuration arrives through the configured map under Name.
func New ¶
func New() *Plugin
New creates a wgpu plugin. Its Config is supplied at Init through kernel.New's config map, so New takes no arguments.
func (*Plugin) Dependencies ¶
func (p *Plugin) Dependencies() []kernel.PluginName
Dependencies reports the plugins wgpu requires: gfx (whose backend and viewport it drives) and input (to which it forwards OS input events).
func (*Plugin) Register ¶
Register resolves the configuration (nil -> DefaultConfig, otherwise the provided wgpu.Config — build it from DefaultConfig via the With* setters), builds the gogpu App, and registers its commands. It does not block; the main loop starts in Run.
func (*Plugin) Run ¶
func (p *Plugin) Run(k kernel.Executioner) error
Run owns the calling (main) thread: it wires the gogpu callbacks to k, starts a watcher that quits the gogpu App when the engine's context is canceled, then runs the App's blocking main loop. Run returns when the window closes (or the app quits), after which the engine shuts down. The callbacks are wired here rather than in Register because that is where a Kernel first exists; the captured value is immutable, so the main and render threads share it safely.
Source Files