1# WLTurbo - Wayland Client Library for Go
2
3A performance-focused Wayland client library that provides the foundational protocol implementation for building Wayland applications and libraries.
4
5## Overview
6
7WLTurbo is a low-level Wayland client library that handles core protocol communication. It serves as the base layer for higher-level libraries like [libwldevices-go](https://github.com/bnema/libwldevices-go) which implement specific Wayland protocol extensions.
8
9## Architecture
10
11WLTurbo provides the foundational Wayland client infrastructure:
12
13- **Core Protocol Objects**: Display, Registry, Compositor, Surface, Seat, Region
14- **Event Dispatching**: Efficient routing of Wayland events to handlers
15- **Connection Management**: Unix socket communication with the compositor
16- **Memory Management**: Shared memory support via file descriptor passing
17
18Higher-level protocol implementations (virtual input devices, output management, etc.) are intentionally left to specialized libraries that build on top of WLTurbo.
19
20## Generated protocols
21
22`protocol/core` provides core Wayland (including data-device); `protocol/xdgshell` provides xdg-shell; `protocol/linuxdmabuf` provides linux-dmabuf v4 feedback; `protocol/drmsyncobj` provides linux-drm-syncobj v1; `protocol/viewporter` provides viewporter; `protocol/fractionalscale` provides fractional-scale v1; and `protocol/textinput` provides text-input v3. Bindings handle wire messages and object lifecycle; applications decide compositor policy.
23
24After `display.Roundtrip()` discovers globals, call `display.Registry().BindNegotiated(interfaceName, supportedVersion, proxy)` to bind at the lesser of the advertised and supported versions. It returns the negotiated version; use `errors.Is(err, wlturbo.ErrGlobalNotFound)` to handle absent optional globals.
25
26## Features
27
28- **Stream framing**: messages split across or coalesced within socket reads are framed exactly; event bodies are not copied.
29- **Descriptor ownership**: received FDs belong to the event that declares them and are closed if a handler does not take them.
30- **Object lifecycle**: destroyed objects stay as zombies until `delete_id`, so events already in flight are dropped instead of failing the connection.
31- **Version checks**: generated requests newer than the bound object version return `ErrVersionTooLow` before anything is sent.
32- **Allocation-free requests**: marshaling fixed-size requests does not allocate.
33
34## Quick Start
35
36```go
37package main
38
39import (
40    "github.com/bnema/wlturbo/wl"
41)
42
43func main() {
44    // Connect to Wayland display
45    display, err := wl.Connect("")
46    if err != nil {
47        panic(err)
48    }
49    defer display.Close()
50
51    // Basic event loop. Handlers run inside Dispatch and must not call
52    // Dispatch or Roundtrip on the same display.
53    for {
54        if err := display.Dispatch(); err != nil {
55            break
56        }
57    }
58}
59```
60
61For device control and input injection, use [libwldevices-go](https://github.com/bnema/libwldevices-go) which builds on top of WLTurbo.
62
63## Requirements
64
65- **Go 1.27+**
66- **Linux** with Wayland compositor
67- **Unix sockets** support
68
69## License
70
71MIT License - see LICENSE file for details
72
73## Contributing
74
75Contributions welcome! Areas of focus:
76- Performance improvements
77- Additional protocol object support
78- Documentation and examples
79- Benchmark suite