libwaylandclient

libwayland-client is the client-side library for the Wayland display server protocol. It provides the C API that applications use to communicate with a Wayland compositor, manage objects, and handle events. The library exposes core Wayland objects such as wl_display, wl_registry, wl_surface, and input and output interfaces, allowing a client to connect to a compositor, discover globals, and create and manage surfaces and buffers.

A typical workflow starts with connecting to the display using wl_display_connect, followed by obtaining the registry with wl_display_get_registry. The client listens for global announcements and binds to required interfaces (for example wl_compositor, wl_shm, and protocol-specific objects like xdg_wm_base for modern shells). After creating a surface via the compositor (wl_compositor_create_surface), the client may create a role surface through protocol extensions such as xdg-shell (e.g., xdg_wm_base_get_xdg_surface, then xdg_surface_get_toplevel).

Rendering relies on buffers provided by wl_shm or other backends; the client attaches a buffer to the surface with wl_surface_attach, marks damaged regions with wl_surface_damage, and commits changes with wl_surface_commit. Event handling is done through the compositor’s event loop, with functions like wl_display_dispatch, wl_display_roundtrip, and support for per-thread event queues when needed.

libwayland-client works in tandem with protocol headers (often generated from XML) and protocol extensions such as xdg-shell and other Wayland protocols obtained via wayland-protocols. It is commonly used directly by applications and by toolkit libraries that implement Wayland clients. The library is part of the Wayland project and is distributed under its permissive licensing terms.