webgpu

package
v0.11.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: BSD-3-Clause Imports: 10 Imported by: 0

Documentation

Overview

Package webgpu is the host side of wasi:webgpu (wasi-gfx, wasi:webgpu@0.3.0-rc.2) for core modules: every function of the WIT interface is a typed import of one host module, lowered and lifted with the Canonical ABI (package wit) by hand, without a component-model runtime. Resources are handles in a per-process table.

The functions run against a Backend: in the browser, WebGPU in the engine's worker (backend_js.go); elsewhere none, so get-gpu works and request-adapter answers "none", and a guest can test for a GPU portably. A process without the container's "gpu" capability (run --gpu) gets no adapter either.

Index

Constants

View Source
const MaxCoordinate = 1 << 16

MaxCoordinate bounds a pointer coordinate: far outside any surface (1920x1080 at most) but finite.

View Source
const MaxInputStreams = 64

MaxInputStreams bounds the streams one surface serves (all kinds).

View Source
const MaxKeyText = 64

MaxKeyText bounds a key event's text, in bytes.

View Source
const MaxQueued = 256

MaxQueued bounds the events a stream keeps for a guest that does not read them: past it the oldest is dropped (and counted).

View Source
const RootModule = wit.RootModule

RootModule is the module of the waitable-set built-ins.

Variables

View Source
var DefaultLimits = Limits{Handles: 4096, MemoryBytes: 256 << 20, ShaderBytes: 1 << 20, Pipelines: 256}

DefaultLimits are the per-process quotas.

View Source
var ErrHandles = errors.New("too many live resources")

ErrHandles is the quota error of New.

View Source
var InputKinds = []string{"pointer-up", "pointer-down", "pointer-move", "key-up", "key-down"}

InputKinds are the kinds a surface serves.

View Source
var Interface = func() *wit.Interface {
	ifs, err := wit.Parse(witdata.WebGPU)
	if err != nil {
		panic(err)
	}
	return ifs["webgpu"]
}()

Interface is the parsed wasi:webgpu interface.

View Source
var SurfaceInterfaces = func() map[string]*wit.Interface {
	ifs, err := wit.ParseFiles([]*wit.Interface{Interface}, witdata.Surface)
	if err != nil {
		panic(err)
	}
	return ifs
}()

SurfaceInterfaces are wasi-gfx:surface's surface and surface-webgpu, as this module declares and serves them (webgpu/wit/surface.wit).

Functions

func HostModules added in v0.5.0

func HostModules(b Backend) []wasi.HostModule

HostModules is NewModules as the engine's host-module list.

func KeyFromCode added in v0.6.0

func KeyFromCode(code string) (uint32, bool)

KeyFromCode maps a UI Events KeyboardEvent.code ("KeyA", "Digit0", "ArrowUp", "NumpadClearEntry") to the index of wasi-gfx:surface's key enum ("key-a", "digit0", "arrow-up", "numpad-clear-entry"); ok is false for a code it does not have (the event's key is then none).

func Trapf

func Trapf(format string, a ...any) error

Trapf makes a TrapError.

Types

type Backend

type Backend interface {
	// Open starts a process's session.
	Open(p Process, lim Limits, h *Handles) Session
}

Backend serves the functions for one process.

type Destroyer

type Destroyer interface{ Destroy() }

Destroyer is implemented by objects that release something when their handle is dropped or the process ends.

type Handles

type Handles struct {
	// contains filtered or unexported fields
}

Handles is a process's resource table: handles start at 1 (0 is never valid), each tagged with its resource type.

func (*Handles) Drop

func (h *Handles) Drop(n uint32, res string) error

Drop removes handle n (a res), destroying its object.

func (*Handles) Get

func (h *Handles) Get(n uint32, res string) (any, error)

Get returns handle n's object, which must be a res.

func (*Handles) Len

func (h *Handles) Len() int

Len is the number of live handles.

func (*Handles) New

func (h *Handles) New(res string, obj any) (uint32, error)

New registers obj as a resource of type res and returns its handle.

type InputEvent added in v0.6.0

type InputEvent struct {
	// Kind is "pointer-down", "pointer-up", "pointer-move", "key-down" or
	// "key-up" (the surface methods on-<kind>).
	Kind string
	// X, Y: pointers, in surface pixels from the top-left corner (the page
	// scales from the pane).
	X, Y float64
	// Code is KeyboardEvent.code ("KeyA"); an unknown code is a key of
	// none. Text is the text the key produces (KeyboardEvent.key when it is
	// one character), "" for none.
	Code, Text             string
	Alt, Ctrl, Meta, Shift bool
}

InputEvent is a pointer or key event the page (the dashboard pane that shows a surface) sends for that surface; the host turns it into a wasi-gfx:surface pointer-event or key-event on the guest's streams of that kind.

type Limits

type Limits struct {
	Handles     int   // live resources (default 4096)
	MemoryBytes int64 // buffer and texture bytes alive (default 256 MiB)
	ShaderBytes int   // one WGSL source (default 1 MiB)
	Pipelines   int   // pipelines alive (default 256)
}

Limits bound one process's use of the GPU.

type Module

type Module struct {
	Backend Backend
	Limits  Limits
	// contains filtered or unexported fields
}

Module is a host module serving one WIT interface: wasi:webgpu, or one of wasi-gfx:surface's. The modules of one Backend share, per process, one handle table and one session, so a texture a surface context returns is a wasi:webgpu resource like any other.

func NewModule

func NewModule(b Backend) *Module

NewModule serves wasi:webgpu with a backend (nil: no GPU anywhere).

func NewModules added in v0.5.0

func NewModules(b Backend) []*Module

NewModules serves wasi:webgpu, wasi-gfx:surface (surface, surface-webgpu) and the waitable-set built-ins ($root) with one backend: register all four.

func (*Module) Funcs

func (m *Module) Funcs() []wasi.HostFunc

Funcs implements wasi.HostModule: every function of the interface, with its Canonical ABI core signature, a drop per resource, and the stream built-ins of the functions returning streams.

func (*Module) Module

func (m *Module) Module() string

Module implements wasi.HostModule.

func (*Module) Open

func (m *Module) Open(p *wasi.Proc) wasi.Instance

Open implements wasi.HostModule.

type Process added in v0.5.0

type Process struct {
	GPU       bool   // the process has the gpu capability
	Container string // its container's label (wasi.Config.Label), for surfaces
}

Process is what a Backend knows of the process it serves.

type Session

type Session interface {
	// Call runs import name with lifted arguments and returns the result
	// value (nil for none). A *TrapError traps the guest.
	Call(name string, args []any) (any, error)
	// Async reports whether name waits on the platform (WebGPU promises):
	// such calls run off the host call.
	Async(name string) bool
	// Close releases everything (the process ended).
	Close()
}

Session is one process's GPU state.

type Stream added in v0.6.0

type Stream struct {
	Elem *wit.Type
	// contains filtered or unexported fields
}

Stream is the readable end of a stream the host writes (a surface's input events).

func NewStream added in v0.6.0

func NewStream(elem *wit.Type) *Stream

NewStream makes a readable end of elements of type elem.

func (*Stream) CloseWriter added in v0.6.0

func (s *Stream) CloseWriter()

CloseWriter ends the stream: once the queue is read, reads report DROPPED.

func (*Stream) Destroy added in v0.6.0

func (s *Stream) Destroy()

Destroy implements Destroyer.

func (*Stream) Dropped added in v0.6.0

func (s *Stream) Dropped() uint64

Dropped is how many events were lost to MaxQueued.

func (*Stream) Push added in v0.6.0

func (s *Stream) Push(v any)

Push writes one event (a value of s.Elem); it never blocks.

func (*Stream) SetOnClose added in v0.6.0

func (s *Stream) SetOnClose(f func())

SetOnClose sets what runs when the guest drops the end (or its process ends).

type TrapError

type TrapError struct{ Msg string }

TrapError traps the guest (the Canonical ABI's answer to an invalid handle, or a quota exceeded where the API has no error to report).

func (*TrapError) Error

func (e *TrapError) Error() string

type WaitSet added in v0.6.0

type WaitSet struct {
	// contains filtered or unexported fields
}

WaitSet is a waitable set: the streams a guest waits on together.

func (*WaitSet) Destroy added in v0.6.0

func (w *WaitSet) Destroy()

Destroy implements Destroyer: the process ended; wake a waiter.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL