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
- Variables
- func PackARGB8888(dst []byte, dstStride int, src []byte, srcStride, w, h int)
- type Buffer
- type ByteOrder
- type Callback
- type Compositor
- type Conn
- type DataDevice
- type DataDeviceManager
- type DataOffer
- type DataSource
- type Display
- type Fixed
- type Global
- type Key
- type Keyboard
- type Keymap
- type Output
- type Pointer
- type Registry
- func (r *Registry) Compositor() (*Compositor, error)
- func (r *Registry) DataDeviceManager() (*DataDeviceManager, error)
- func (r *Registry) Find(iface string) (Global, bool)
- func (r *Registry) Globals() []Global
- func (r *Registry) Outputs() ([]*Output, error)
- 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
- func (s *Surface) Attach(buf *Buffer, x, y int) error
- func (s *Surface) Commit() error
- func (s *Surface) Damage(x, y, w, h int) error
- func (s *Surface) DamageBuffer(x, y, w, h int) error
- func (s *Surface) Destroy() error
- func (s *Surface) Frame() (*Callback, error)
- func (s *Surface) ID() uint32
- func (s *Surface) SetBufferScale(scale int) error
- 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 ¶
var ErrWoken = errors.New("wayland: dispatch woken")
ErrWoken is what Dispatch returns when Conn.Wake interrupted the wait rather than an event arriving. It is not a failure: the caller has been asked to do something — repaint, usually — and should carry on dispatching.
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.
func (*Conn) Dispatch ¶
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) Roundtrip ¶
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.
func (*Conn) Wake ¶ added in v0.32.0
Wake makes the next (or currently blocked) Conn.Dispatch return ErrWoken.
It is safe to call from any goroutine and returns without waiting. Calling it repeatedly before the dispatch loop gets there is not an error and costs nothing: one wakeup is armed at a time, because a second would only buy a second identical trip round the loop.
A transport that cannot be interrupted — the in-process fake — returns an error rather than pretending to have woken anybody.
type DataDevice ¶ added in v0.29.0
type DataDevice struct {
// contains filtered or unexported fields
}
DataDevice is one seat's view of the clipboard: what it can be given, and where a selection is announced.
func (*DataDevice) Selection ¶ added in v0.29.0
func (d *DataDevice) Selection() *DataOffer
Selection is the offer currently on the clipboard, or nil when it holds nothing this client can read.
func (*DataDevice) SetSelection ¶ added in v0.29.0
func (d *DataDevice) SetSelection(source *DataSource) error
SetSelection puts source on the clipboard, quoting the seat's most recent input serial.
The serial is not ceremony: a compositor grants the clipboard on the strength of a real user event, so a client that has never been interacted with is refused. That refusal is silent — there is no reply to this request — which is why a caller that has seen no input should expect nothing to happen.
type DataDeviceManager ¶ added in v0.29.0
type DataDeviceManager struct {
// contains filtered or unexported fields
}
DataDeviceManager is the wl_data_device_manager global: the factory for sources (what this client can give) and devices (what it can be given).
func (*DataDeviceManager) CreateSource ¶ added in v0.29.0
func (m *DataDeviceManager) CreateSource() *DataSource
CreateSource makes a data source.
func (*DataDeviceManager) GetDevice ¶ added in v0.29.0
func (m *DataDeviceManager) GetDevice(seat *Seat) *DataDevice
GetDevice makes the data device for a seat.
type DataOffer ¶ added in v0.29.0
type DataOffer struct {
// contains filtered or unexported fields
}
DataOffer is something another client is offering: the MIME types it can produce, and a way to ask for the bytes.
func (*DataOffer) Mimes ¶ added in v0.29.0
Mimes are the types the offer advertises, in the order it advertised them.
type DataSource ¶ added in v0.29.0
type DataSource struct {
// Send is called when somebody pastes: the compositor names the MIME type
// it wants and supplies a file descriptor to write the bytes into. The
// callback owns the descriptor and must close it — leaving it open leaves
// the paster blocked on a read that will never end.
Send func(mime string, fd int)
// Cancelled fires when the selection is taken over by another client, or
// when the compositor is done with the source. Nothing more will be asked
// of it.
Cancelled func()
// contains filtered or unexported fields
}
DataSource is something this client can hand out: a set of MIME types and the bytes behind them.
func (*DataSource) Destroy ¶ added in v0.29.0
func (s *DataSource) Destroy() error
Destroy releases the source. A source destroyed while it owns the selection takes the clipboard's contents with it.
func (*DataSource) Offer ¶ added in v0.29.0
func (s *DataSource) Offer(mime string) error
Offer declares a MIME type this source can produce. Order is preference: the first type both sides understand is the one that gets used.
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 Output ¶ added in v0.34.0
type Output struct {
// OnScale fires when done publishes a scale different from the last one.
OnScale func(scale int)
// contains filtered or unexported fields
}
Output is a wl_output: one screen, and the thing that knows its scale.
func (*Output) ID ¶ added in v0.34.0
ID returns the output's object id, which is what wl_surface.enter names.
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) DataDeviceManager ¶ added in v0.29.0
func (r *Registry) DataDeviceManager() (*DataDeviceManager, error)
DataDeviceManager finds and binds the wl_data_device_manager global.
A compositor without one has no clipboard to offer, which is a fact about the session rather than an error in this client — a bare surface-only compositor is a legitimate thing to run.
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) Outputs ¶ added in v0.34.0
Outputs binds every wl_output the compositor advertises.
Every one, not the first: a laptop plugged into an external screen has two, with different scales, and which one a window is on is a question only wl_surface.enter can answer.
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.
func (*Seat) LastSerial ¶ added in v0.28.0
LastSerial is the most recent input serial from this seat, or 0 when the user has not interacted with the window yet.
A caller quoting 0 should expect to be refused rather than obeyed: a compositor grants clipboard ownership on the strength of a real event, which is what stops a background application from taking the clipboard while the user is elsewhere.
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 {
// OnEnter and OnLeave report the wl_output object id a surface has appeared
// on or left. A window that wants the panel's own pixels has to know which
// panel it is on, and this is the only thing that says so.
OnEnter func(output uint32)
OnLeave func(output uint32)
// 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).
func (*Surface) Frame ¶
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) SetBufferScale ¶ added in v0.34.0
SetBufferScale declares how many buffer pixels the surface puts in one logical point.
Without it a compositor on a scale-2 screen takes the buffer as being in logical units and stretches it: the application is drawn at half the panel's resolution and then blown up. With it, and a buffer allocated scale times larger, the pixels are the panel's own.
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.
Source Files