wayland

package
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Aug 9, 2026 License: BSD-3-Clause Imports: 12 Imported by: 0

Documentation

Overview

Package wayland is a from-scratch, pure-Go (CGO-free, zero non-stdlib dependency) implementation of the Wayland wire protocol, spoken directly over a UNIX-domain stream socket.

It mirrors the sovereign transport+codec approach of the sibling internal/x11 package and of github.com/go-freedesktop/dbus: no libwayland, no wayland-scanner, no cgo — the wire format is encoded and decoded here, byte for byte, per the Wayland protocol specification, and file descriptors are passed over the socket via SCM_RIGHTS ancillary control messages using only the Go standard library.

The Wayland wire format is object-oriented. Every message is

uint32 object-id      (the target/sender object)
uint32 (size<<16 | opcode)   size in bytes incl. this 8-byte header
... typed arguments, each padded to a 4-byte boundary ...

Arguments are int (i32), uint (u32), fixed (signed 24.8), string (length-prefixed, NUL-terminated, padded), array (length-prefixed, padded), object (u32 id), new_id (u32 id, optionally interface+version prefixed) and fd (carried out-of-band, occupying no bytes in the body).

Integers travel in the host's native byte order (both peers share the machine), so the codec is parametrised by a binary.ByteOrder that defaults to binary.NativeEndian; tests drive both endian paths on any host, and the s390x CI lane exercises the big-endian path on real big-endian hardware.

Index

Constants

View Source
const (
	SeatCapabilityPointer  = 1
	SeatCapabilityKeyboard = 2
	SeatCapabilityTouch    = 4
)

Seat capability bits (wl_seat.capability).

View Source
const (
	BtnLeft   = 0x110
	BtnRight  = 0x111
	BtnMiddle = 0x112
)

Linux input-event-codes button numbers reported by wl_pointer.button.

View Source
const (
	StateReleased = 0
	StatePressed  = 1
)

wl_pointer.button / wl_keyboard.key state values.

View Source
const (
	AxisVerticalScroll   = 0
	AxisHorizontalScroll = 1
)

wl_pointer.axis values.

View Source
const (
	KeymapFormatNoKeymap = 0
	KeymapFormatXkbV1    = 1
)

wl_keyboard.keymap format values.

View Source
const (
	ShmFormatARGB8888 = 0
	ShmFormatXRGB8888 = 1
)

wl_shm pixel formats (a subset of the DRM fourcc set). ARGB8888 stores a 32-bit value 0xAARRGGBB per pixel; on the wire the region is filled with that value in the machine's native byte order, which the compositor — running on the same machine — reads back identically.

Variables

This section is empty.

Functions

func PackARGB8888

func PackARGB8888(dst []byte, dstStride int, src []byte, srcStride, w, h int)

PackARGB8888 converts a w×h RGBA source (4 bytes per pixel, R,G,B,A byte order, srcStride bytes per row) into WL_SHM_FORMAT_ARGB8888 pixels in dst (dstStride bytes per row). Each destination pixel is the 32-bit value 0xAARRGGBB written in the machine's native byte order — exactly what a compositor on the same machine reads back — so the packing is correct on little- and big-endian hosts alike. The 32-bit word is assembled and stored via the concrete binary.NativeEndian (not the ByteOrder interface) so the compiler inlines it to a single word store instead of a per-pixel interface method call; rows are resliced so the inner loop's indices are provably in range.

Types

type Buffer

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

Buffer is a wl_buffer: a rectangular view into a pool the compositor can read while it is attached to a surface. released tracks whether the compositor currently holds it (false) or has handed it back (true).

func (*Buffer) Destroy

func (b *Buffer) Destroy() error

Destroy releases the buffer object.

func (*Buffer) Released

func (b *Buffer) Released() bool

Released reports whether the buffer is free for the client to redraw.

type ByteOrder

type ByteOrder = binary.ByteOrder

ByteOrder is the wire byte order. Wayland uses the machine's native order; NativeOrder resolves it, and the codec is parametrised so both paths are testable on any host.

var NativeOrder ByteOrder = binary.NativeEndian

NativeOrder is the byte order used on the wire in production: the host's native endianness, which both the client and the compositor share.

type Callback

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

Callback is a one-shot wl_callback: it fires its done event once and is then finished.

type Compositor

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

Compositor is the wl_compositor global: it creates surfaces (and regions, unused here).

func (*Compositor) CreateSurface

func (c *Compositor) CreateSurface() (*Surface, error)

CreateSurface issues wl_compositor.create_surface and returns the surface.

type Conn

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

Conn is a Wayland connection: the object table, the request encoder and the event dispatcher over a transport. It is transport-agnostic — the same machine drives a real UNIX socket in production and an in-process fake compositor in tests.

func New

func New(c *net.UnixConn) *Conn

New builds a connection over a dialed UNIX-domain socket using the host's native wire byte order — the production entry point for the window layer. It is Linux-only: it wires the SCM_RIGHTS socket transport, which is the only way to pass wl_shm/keymap descriptors to the compositor, and the backend itself only runs on Linux. The transport-agnostic NewConn (used by the in-process tests) stays cross-platform in conn.go.

func NewConn

func NewConn(t transport, order ByteOrder) *Conn

NewConn builds a connection over t using the given wire byte order and installs the wl_display singleton. Order is normally NativeOrder.

func (*Conn) Close

func (c *Conn) Close() error

Close releases the underlying transport.

func (*Conn) Dispatch

func (c *Conn) Dispatch() error

Dispatch reads and delivers exactly one event. Events for objects with no handler (e.g. an object destroyed after the compositor queued an event for it) are read and discarded. A latched protocol error is returned in preference to anything else.

func (*Conn) Display

func (c *Conn) Display() *Display

Display returns the wl_display singleton.

func (*Conn) Err

func (c *Conn) Err() error

Err returns the latched fatal protocol error, if any.

func (*Conn) Roundtrip

func (c *Conn) Roundtrip() error

Roundtrip issues a wl_display.sync and dispatches events until the resulting callback fires, i.e. until the compositor has processed every request sent before the sync. It is the Wayland analogue of an X11 round-tripping request.

type Display

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

Display is the wl_display singleton (object id 1): the root of every connection. It creates the registry and issues synchronisation callbacks, and it is the sink for global protocol errors.

func (*Display) GetRegistry

func (d *Display) GetRegistry() (*Registry, error)

GetRegistry issues wl_display.get_registry and returns the registry proxy.

type Fixed

type Fixed int32

Fixed is a Wayland 24.8 signed fixed-point number as carried on the wire (the raw i32 value equal to the real number times 256).

func FixedFromFloat

func FixedFromFloat(f float64) Fixed

FixedFromFloat builds a Fixed from a float64 (rounded to 1/256).

func FixedFromInt

func FixedFromInt(i int) Fixed

FixedFromInt builds a Fixed from a whole integer.

func (Fixed) Float

func (f Fixed) Float() float64

Float returns the value as a float64.

func (Fixed) Int

func (f Fixed) Int() int

Int returns the truncated integer part (toward zero via arithmetic shift for the fractional bits; matches wl_fixed_to_int).

type Global

type Global struct {
	Name      uint32
	Interface string
	Version   uint32
}

Global is one advertised global: a compositor-assigned name, the interface it implements and the maximum version offered.

type Key

type Key struct {
	// Name is a toolkit key name for a non-character key ("Enter",
	// "ArrowLeft", ...), or "" for a character / modifier key.
	Name string
	// Rune is the committed character for a printable key; valid only when
	// HasRune is true.
	Rune rune
	// HasRune reports whether Rune is meaningful.
	HasRune bool
	// IsModifier reports a modifier key (Shift/Control/Alt/...); such keys
	// deliver no toolkit event.
	IsModifier bool
}

Key is the resolved meaning of a hardware key at a given shift level.

type Keyboard

type Keyboard struct {
	OnKey       func(evdevCode uint32, pressed bool)
	OnModifiers func()
	OnEnter     func()
	OnLeave     func()
	// contains filtered or unexported fields
}

Keyboard is a wl_keyboard device. It ingests the xkb keymap, tracks modifier state and delivers key press/release through OnKey.

func (*Keyboard) Alt

func (k *Keyboard) Alt() bool

Alt reports whether Alt is currently held.

func (*Keyboard) Ctrl

func (k *Keyboard) Ctrl() bool

Ctrl reports whether Control is currently held.

func (*Keyboard) Keymap

func (k *Keyboard) Keymap() *Keymap

Keymap returns the parsed keymap.

func (*Keyboard) Release

func (k *Keyboard) Release() error

Release releases the keyboard object.

func (*Keyboard) RepeatDelay

func (k *Keyboard) RepeatDelay() int

RepeatDelay returns the key-repeat delay in milliseconds.

func (*Keyboard) RepeatRate

func (k *Keyboard) RepeatRate() int

RepeatRate returns the key-repeat rate in keys per second (0 disables).

func (*Keyboard) Shift

func (k *Keyboard) Shift() bool

Shift reports whether Shift is currently held.

type Keymap

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

Keymap is a parsed xkb keymap: the per-keycode list of level keysym names (group 1 only), keyed by xkb keycode.

func ParseKeymap

func ParseKeymap(text string) *Keymap

ParseKeymap parses an xkb_v1 keymap document. An empty or unparsable document yields a Keymap that resolves every key to nothing (safe: keys simply produce no events), so a compositor sending a keymap this minimal parser does not understand degrades gracefully rather than crashing.

func (*Keymap) Lookup

func (km *Keymap) Lookup(evdevCode uint32, shift bool) Key

Lookup resolves an evdev keycode at the given shift level into a Key. An unknown keycode or empty level yields the zero Key (nothing to deliver).

type Pointer

type Pointer struct {
	OnEnter  func(x, y Fixed)
	OnLeave  func()
	OnMotion func(x, y Fixed)
	OnButton func(button uint32, pressed bool)
	OnAxis   func(axis uint32, value Fixed)
	// contains filtered or unexported fields
}

Pointer is a wl_pointer device. It decodes enter/leave/motion/button/axis events and delivers them through the callback fields the window layer sets.

func (*Pointer) Release

func (p *Pointer) Release() error

Release releases the pointer object.

type Registry

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

Registry is wl_registry: it enumerates the compositor's globals and binds them into interface proxies.

func (*Registry) Compositor

func (r *Registry) Compositor() (*Compositor, error)

Compositor finds and binds the wl_compositor global.

func (*Registry) Find

func (r *Registry) Find(iface string) (Global, bool)

Find returns the advertised global for the given interface name and whether it was found. When several versions are advertised the first is returned (compositors advertise one global per interface).

func (*Registry) Globals

func (r *Registry) Globals() []Global

Globals returns a copy of the currently advertised globals.

func (*Registry) Seat

func (r *Registry) Seat() (*Seat, error)

Seat finds and binds the wl_seat global.

func (*Registry) Shm

func (r *Registry) Shm() (*Shm, error)

Shm finds and binds the wl_shm global.

func (*Registry) VirtualKeyboardManager added in v0.3.0

func (r *Registry) VirtualKeyboardManager() (*VirtualKeyboardManager, error)

VirtualKeyboardManager binds the zwp_virtual_keyboard_manager_v1 global.

func (*Registry) VirtualPointerManager added in v0.3.0

func (r *Registry) VirtualPointerManager() (*VirtualPointerManager, error)

VirtualPointerManager binds the zwlr_virtual_pointer_manager_v1 global.

func (*Registry) XdgWmBase

func (r *Registry) XdgWmBase() (*XdgWmBase, error)

XdgWmBase finds and binds the xdg_wm_base global (stable xdg-shell).

type Seat

type Seat struct {

	// OnCapabilities, if set, is invoked every time the compositor updates
	// the seat's capability mask — including after bring-up, so a device
	// that appears later (e.g. a keyboard hot-plugged, or a virtual keyboard
	// attached to the seat) can be obtained then. It enables dynamic input
	// hot-plug rather than a one-shot read at connection time.
	OnCapabilities func(caps uint32)
	// contains filtered or unexported fields
}

Seat is the wl_seat global: a group of input devices (pointer, keyboard, touch). It advertises which devices are present and manufactures the per-device proxies.

func (*Seat) Capabilities

func (s *Seat) Capabilities() uint32

Capabilities returns the advertised capability bitmask.

func (*Seat) GetKeyboard

func (s *Seat) GetKeyboard() (*Keyboard, error)

GetKeyboard obtains the seat's keyboard device.

func (*Seat) GetPointer

func (s *Seat) GetPointer() (*Pointer, error)

GetPointer obtains the seat's pointer device.

func (*Seat) HasKeyboard

func (s *Seat) HasKeyboard() bool

HasKeyboard reports whether the seat has a keyboard device.

func (*Seat) HasPointer

func (s *Seat) HasPointer() bool

HasPointer reports whether the seat has a pointer device.

func (*Seat) Name

func (s *Seat) Name() string

Name returns the seat's human-readable name.

func (*Seat) Release

func (s *Seat) Release() error

Release releases the seat object.

type Shm

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

Shm is the wl_shm global: it advertises supported pixel formats and creates shared-memory pools.

func (*Shm) CreatePool

func (s *Shm) CreatePool(size int) (*ShmPool, error)

CreatePool allocates a shared-memory region of size bytes and creates a wl_shm_pool over it, passing the descriptor to the compositor.

func (*Shm) Supports

func (s *Shm) Supports(format uint32) bool

Supports reports whether the compositor advertised the given format.

type ShmPool

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

ShmPool is a wl_shm_pool: a mapped memory region from which buffers are carved.

func (*ShmPool) CreateBuffer

func (p *ShmPool) CreateBuffer(offset, width, height, stride int, format uint32) (*Buffer, error)

CreateBuffer carves a wl_buffer from the pool at byte offset with the given geometry and pixel format.

func (*ShmPool) Data

func (p *ShmPool) Data() []byte

Data returns the writable pixel store backing the pool.

func (*ShmPool) Destroy

func (p *ShmPool) Destroy() error

Destroy releases the pool object and its backing region. The already created buffers remain valid until they too are destroyed.

type Surface

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

Surface is a wl_surface: the drawable region attached to a shell role and filled from a wl_buffer.

func (*Surface) Attach

func (s *Surface) Attach(buf *Buffer, x, y int) error

Attach binds buf as the surface's pending content at the given offset. A nil buffer detaches (attaches the null object).

func (*Surface) Commit

func (s *Surface) Commit() error

Commit atomically applies the pending surface state (attached buffer, damage, frame request) to the displayed surface.

func (*Surface) Damage

func (s *Surface) Damage(x, y, w, h int) error

Damage marks a rectangle of the surface (in surface coordinates) as changed since the last commit.

func (*Surface) DamageBuffer

func (s *Surface) DamageBuffer(x, y, w, h int) error

DamageBuffer marks a rectangle in buffer coordinates as changed (the scale-independent damage request preferred since wl_surface v4).

func (*Surface) Destroy

func (s *Surface) Destroy() error

Destroy releases the surface object.

func (*Surface) Frame

func (s *Surface) Frame() (*Callback, error)

Frame requests a throttling callback that fires when the compositor is ready for the next frame; the returned Callback's done event carries a timestamp and marks it ready.

func (*Surface) ID

func (s *Surface) ID() uint32

ID returns the surface's object id.

type VirtualKeyboard added in v0.3.0

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

VirtualKeyboard is a zwp_virtual_keyboard_v1: a client-driven keyboard on the seat. A keymap must be uploaded before any key event.

func (*VirtualKeyboard) Destroy added in v0.3.0

func (k *VirtualKeyboard) Destroy() error

Destroy releases the virtual keyboard (removing the seat's keyboard capability if it was the only one).

func (*VirtualKeyboard) Key added in v0.3.0

func (k *VirtualKeyboard) Key(time, key, state uint32) error

Key injects a key press or release. key is the Linux evdev keycode (e.g. 30 for KEY_A); state is StatePressed or StateReleased.

func (*VirtualKeyboard) Keymap added in v0.3.0

func (k *VirtualKeyboard) Keymap(format uint32, fd int, size uint32) error

Keymap uploads the xkb keymap the virtual keyboard's key codes are interpreted against, passing the (read-only) descriptor over SCM_RIGHTS. The compositor forwards this same keymap to focused clients.

func (*VirtualKeyboard) Modifiers added in v0.3.0

func (k *VirtualKeyboard) Modifiers(depressed, latched, locked, group uint32) error

Modifiers sets the active modifier masks (depressed/latched/locked/group).

type VirtualKeyboardManager added in v0.3.0

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

VirtualKeyboardManager is the zwp_virtual_keyboard_manager_v1 global: it manufactures virtual keyboards bound to a seat.

func (*VirtualKeyboardManager) CreateKeyboard added in v0.3.0

func (m *VirtualKeyboardManager) CreateKeyboard(seat *Seat) (*VirtualKeyboard, error)

CreateKeyboard creates a virtual keyboard attached to seat.

type VirtualPointer added in v0.3.0

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

VirtualPointer is a zwlr_virtual_pointer_v1: a client-driven pointer on the seat. Absolute motion maps a coordinate within an extent onto the output.

func (*VirtualPointer) Button added in v0.3.0

func (p *VirtualPointer) Button(time, button, state uint32) error

Button injects a pointer button press or release. button is a Linux evdev button code (e.g. BtnLeft); state is StatePressed or StateReleased.

func (*VirtualPointer) Destroy added in v0.3.0

func (p *VirtualPointer) Destroy() error

Destroy releases the virtual pointer.

func (*VirtualPointer) Frame added in v0.3.0

func (p *VirtualPointer) Frame() error

Frame groups the preceding pointer requests into one logical event, as the compositor requires before it dispatches them.

func (*VirtualPointer) MotionAbsolute added in v0.3.0

func (p *VirtualPointer) MotionAbsolute(time, x, y, xExtent, yExtent uint32) error

MotionAbsolute moves the pointer to (x, y) interpreted within the extent (xExtent, yExtent); the compositor scales it onto the output geometry.

type VirtualPointerManager added in v0.3.0

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

VirtualPointerManager is the zwlr_virtual_pointer_manager_v1 global: it manufactures virtual pointers bound to a seat.

func (*VirtualPointerManager) CreatePointer added in v0.3.0

func (m *VirtualPointerManager) CreatePointer(seat *Seat) (*VirtualPointer, error)

CreatePointer creates a virtual pointer attached to seat.

type XdgSurface

type XdgSurface struct {

	// OnConfigure, if set, is called with each configure serial. The window
	// layer acks it (after applying any toplevel size) via AckConfigure.
	OnConfigure func(serial uint32)
	// contains filtered or unexported fields
}

XdgSurface adds window-manager semantics (configure/ack) to a wl_surface.

func (*XdgSurface) AckConfigure

func (xs *XdgSurface) AckConfigure(serial uint32) error

AckConfigure acknowledges a configure serial; the client must do this before committing the buffer that satisfies the configure.

func (*XdgSurface) Configured

func (xs *XdgSurface) Configured() bool

Configured reports whether the compositor has sent the first configure.

func (*XdgSurface) Destroy

func (xs *XdgSurface) Destroy() error

Destroy releases the xdg_surface object.

func (*XdgSurface) GetToplevel

func (xs *XdgSurface) GetToplevel() (*XdgToplevel, error)

GetToplevel gives the xdg_surface the toplevel (application window) role.

func (*XdgSurface) LastSerial

func (xs *XdgSurface) LastSerial() uint32

LastSerial is the most recent configure serial.

type XdgToplevel

type XdgToplevel struct {

	// OnConfigure is called with the compositor-suggested size (0 means "you
	// choose") and the raw states array. The window layer resizes to it.
	OnConfigure func(width, height int, states []byte)
	// OnClose is called when the user asks to close the window.
	OnClose func()
	// contains filtered or unexported fields
}

XdgToplevel is the application-window role: it carries the title/app-id and delivers resize (configure) and close intents.

func (*XdgToplevel) Destroy

func (tl *XdgToplevel) Destroy() error

Destroy releases the xdg_toplevel object.

func (*XdgToplevel) SetAppID

func (tl *XdgToplevel) SetAppID(appID string) error

SetAppID sets the application identifier (used for grouping / .desktop matching).

func (*XdgToplevel) SetTitle

func (tl *XdgToplevel) SetTitle(title string) error

SetTitle sets the window title.

type XdgWmBase

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

XdgWmBase is the xdg_wm_base global (stable xdg-shell): the factory for window-manager surface roles. It answers the compositor's liveness pings automatically so the window is never declared unresponsive.

func (*XdgWmBase) Destroy

func (b *XdgWmBase) Destroy() error

Destroy releases the xdg_wm_base object.

func (*XdgWmBase) GetXdgSurface

func (b *XdgWmBase) GetXdgSurface(surf *Surface) (*XdgSurface, error)

GetXdgSurface gives a wl_surface the xdg_surface role.

func (*XdgWmBase) Pong

func (b *XdgWmBase) Pong(serial uint32) error

Pong answers a liveness ping.

Jump to

Keyboard shortcuts

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