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/godbus/dbus/v5: 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
- func PackARGB8888(dst []byte, dstStride int, src []byte, srcStride, w, h int)
- type Buffer
- type ByteOrder
- type Callback
- type Compositor
- type Conn
- type Display
- type Fixed
- type Global
- type Key
- type Keyboard
- type Keymap
- type Pointer
- type Registry
- func (r *Registry) Compositor() (*Compositor, error)
- func (r *Registry) Find(iface string) (Global, bool)
- func (r *Registry) Globals() []Global
- func (r *Registry) Seat() (*Seat, error)
- func (r *Registry) Shm() (*Shm, error)
- func (r *Registry) VirtualKeyboardManager() (*VirtualKeyboardManager, error)
- func (r *Registry) VirtualPointerManager() (*VirtualPointerManager, error)
- func (r *Registry) XdgWmBase() (*XdgWmBase, error)
- type Seat
- type Shm
- type ShmPool
- type Surface
- type VirtualKeyboard
- type VirtualKeyboardManager
- type VirtualPointer
- type VirtualPointerManager
- type XdgSurface
- type XdgToplevel
- type XdgWmBase
Constants ¶
const ( SeatCapabilityPointer = 1 SeatCapabilityKeyboard = 2 SeatCapabilityTouch = 4 )
Seat capability bits (wl_seat.capability).
const ( BtnLeft = 0x110 BtnRight = 0x111 BtnMiddle = 0x112 )
Linux input-event-codes button numbers reported by wl_pointer.button.
const ( StateReleased = 0 StatePressed = 1 )
wl_pointer.button / wl_keyboard.key state values.
const ( AxisVerticalScroll = 0 AxisHorizontalScroll = 1 )
wl_pointer.axis values.
const ( KeymapFormatNoKeymap = 0 KeymapFormatXkbV1 = 1 )
wl_keyboard.keymap format values.
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 ¶
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).
type 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 ¶
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 ¶
NewConn builds a connection over t using the given wire byte order and installs the wl_display singleton. Order is normally NativeOrder.
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 ¶
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 ¶
FixedFromFloat builds a Fixed from a float64 (rounded to 1/256).
func FixedFromInt ¶
FixedFromInt builds a Fixed from a whole integer.
type Global ¶
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) Logo ¶ added in v0.12.0
Logo reports whether the Super / Meta (⌘/Windows/logo) key is currently held.
func (*Keyboard) RepeatDelay ¶
RepeatDelay returns the key-repeat delay in milliseconds.
func (*Keyboard) RepeatRate ¶
RepeatRate returns the key-repeat rate in keys per second (0 disables).
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 ¶
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.
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.
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 ¶
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) 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.
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 ¶
Capabilities returns the advertised capability bitmask.
func (*Seat) GetKeyboard ¶
GetKeyboard obtains the seat's keyboard device.
func (*Seat) GetPointer ¶
GetPointer obtains the seat's pointer device.
func (*Seat) HasKeyboard ¶
HasKeyboard reports whether the seat has a keyboard device.
func (*Seat) HasPointer ¶
HasPointer reports whether the seat has a pointer device.
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 ¶
CreatePool allocates a shared-memory region of size bytes and creates a wl_shm_pool over it, passing the descriptor to the compositor.
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 ¶
CreateBuffer carves a wl_buffer from the pool at byte offset with the given geometry and pixel format.
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 ¶
Attach binds buf as the surface's pending content at the given offset. A nil buffer detaches (attaches the null object).
func (*Surface) Commit ¶
Commit atomically applies the pending surface state (attached buffer, damage, frame request) to the displayed surface.
func (*Surface) Damage ¶
Damage marks a rectangle of the surface (in surface coordinates) as changed since the last commit.
func (*Surface) DamageBuffer ¶
DamageBuffer marks a rectangle in buffer coordinates as changed (the scale-independent damage request preferred since wl_surface v4).
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) GetXdgSurface ¶
func (b *XdgWmBase) GetXdgSurface(surf *Surface) (*XdgSurface, error)
GetXdgSurface gives a wl_surface the xdg_surface role.