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
- 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
- type Seat
- type Shm
- type ShmPool
- type Surface
- 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.
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.
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) 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).
type Seat ¶
type Seat struct {
// 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 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.