Wayland (protocol)


Wayland is a communication protocol that specifies the communication between a display server and its clients, as well as a C library implementation of that protocol. A display server using the Wayland protocol is called a Wayland compositor, because it additionally performs the task of a compositing window manager.
Wayland is developed by a group of volunteers initially led by Kristian Høgsberg as a free and open-source community-driven project with the aim of replacing the X Window System with a secure and simpler windowing system for Linux and other Unix-like operating systems. The project's source code is published under the terms of the MIT License, a permissive free software license. The Wayland project also develops an implementation of a Wayland compositor called [|Weston].

Overview

The Wayland Display Server project was started by Red Hat developer Kristian Høgsberg in 2008.
Beginning around 2010, Linux desktop graphics have moved from having "a pile of rendering interfaces... all talking to the X server, which is at the center of the universe" towards putting the Linux kernel and its components, Direct Rendering Manager ) "in the middle", with "window systems like X and Wayland... off in the corner". This will be "a much-simplified graphics system offering more flexibility and better performance".
Høgsberg could have added an extension to X as many recent projects have done, but preferred to " X out of the hotpath between clients and the hardware" for reasons explained in the project's FAQ:
Wayland consists of a protocol and a reference implementation named Weston. The project is also developing versions of GTK and Qt that render to Wayland instead of to X. Most applications are expected to gain support for Wayland through one of these libraries without modification to the application.
Initial versions of Wayland have not provided network transparency, though Høgsberg noted in 2010 that network transparency is possible.
It was attempted as a Google Summer of Code project in 2011, but was not successful.
Adam Jackson has envisioned providing remote access to a Wayland application by either "pixel-scraping" or getting it to send a "rendering command stream" across the network. As of early 2013, Høgsberg was experimenting with network transparency using a proxy Wayland server which sends compressed images to the real compositor. In August 2017, GNOME saw the first such pixel-scraping VNC server implementation under Wayland. In modern Wayland compositors, network transparency is handled in an that implements the RemoteDesktop portal.
Many Wayland compositors also include an for common tasks such as a native file picker for native applications and sandboxes such as Flatpak, screen recording, network transparency, screenshots, color picking, and other tasks that could be seen as needing user intervention and being security risks otherwise. Note that xdg-desktop-portal is not Flatpak or Wayland-specific, and can be used with alternative packaging systems and windowing systems.

Software architecture

Protocol architecture

The Wayland protocol follows a client–server model in which clients are the graphical applications requesting the display of pixel buffers on the screen, and the server is the service provider controlling the display of these buffers.
The Wayland reference implementation has been designed as a two-layer protocol:
  • A low-level layer or wire protocol that handles the inter-process communication between the two involved processesclient and compositorand the marshalling of the data that they interchange. This layer is message-based and usually implemented using the kernel IPC services, specifically Unix domain sockets in the case of Linux and other Unix-like operating systems.
  • A high-level layer built upon it, that handles the information that client and compositor need to exchange to implement the basic features of a window system. This layer is implemented as "an asynchronous object-oriented protocol".
While the low-level layer was written manually in C, the high-level layer is automatically generated from a description of the elements of the protocol stored in XML format. Every time the protocol description of this XML file changes, the C source code that implements the protocol can be regenerated to include the new changes, allowing a very flexible, extensible and error-proof protocol.
The reference implementation of Wayland protocol is split in two libraries: a library to be used by Wayland clients called libwayland-client and a library to be used by Wayland compositors called libwayland-server.

Protocol overview

The Wayland protocol is described as an "asynchronous object-oriented protocol". Object-oriented means that the services offered by the compositor are presented as a series of objects living on the same compositor. Each object implements an interface which has a name, a number of methods as well as several associated events. Every request and event has zero or more arguments, each one with a name and a data type. The protocol is asynchronous in the sense that requests do not have to wait for synchronized replies or ACKs, avoiding round-trip delay time and achieving improved performance.
The Wayland clients can make a request on some object if the object's interface supports that request. The client must also supply the required data for the arguments of such request. This is the way the clients request services from the compositor. The compositor in turn sends information back to the client by causing the object to emit events. These events can be emitted by the compositor as a response to a certain request, or asynchronously, subject to the occurrence of internal events or state changes. The error conditions are also signaled as events by the compositor.
For a client to be able to make a request to an object, it first needs to tell the server the ID number it will use to identify that object. There are two types of objects in the compositor: global objects and non-global objects. Global objects are advertised by the compositor to the clients when they are created, while non-global objects are usually created by other objects that already exist as part of their functionality.
The interfaces and their requests and events are the core elements that define the Wayland protocol. Each version of the protocol includes a set of interfaces, along with their requests and events, which are expected to be in any Wayland compositor. Optionally, a Wayland compositor may define and implement its own interfaces that support new requests and events, thereby extending functionality beyond the core protocol. To facilitate changes to the protocol, each interface contains a "version number" attribute in addition to its name; this attribute allows for distinguishing variants of the same interface. Each Wayland compositor exposes not only what interfaces are available, but also the supported versions of those interfaces.

Wayland core interfaces

The interfaces of the current version of Wayland protocol are defined in the file of the Wayland source code. This is an XML file that lists the existing interfaces in the current version, along with their requests, events and other attributes. This set of interfaces is the minimum required to be implemented by any Wayland compositor.
Some of the most basic interfaces of the Wayland protocol are:
  • wl_display the core global object, a special object to encapsulate the Wayland protocol itself
  • wl_registry the global registry object, in which the compositor registers all the global objects that it wants to be available to all clients
  • wl_compositor an object that represents the compositor, and is in charge of combining the different surfaces into one output
  • wl_surface an object representing a rectangular area on the screen, defined by a location, size and pixel content
  • wl_buffer an object that, when attached to a wl_surface object, provides its displayable content
  • wl_output an object representing the displayable area of a screen
  • wl_pointer, wl_keyboard, wl_touch objects representing different input devices like pointers or keyboards
  • wl_seat an object representing a seat in multiseat configurations
A typical Wayland client session starts by opening a connection to the compositor using the wl_display object. This is a special local object that represents the connection and does not live within the server. By using its interface the client can request the wl_registry global object from the compositor, where all the global object names live, and bind those that the client is interested in. Usually the client binds at least a wl_compositor object from where it will request one or more wl_surface objects to show the application output on the display.

Wayland extension interfaces

A Wayland compositor can define and export its own additional interfaces. This feature is used to extend the protocol beyond the basic functionality provided by the core interfaces, and has become the standard way to implement Wayland protocol extensions. Certain compositors can choose to add custom interfaces to provide specialized or unique features. The Wayland reference compositor, Weston, used them to implement new experimental interfaces as a testbed for new concepts and ideas, some of which later became part of the core protocol.

Extension protocols to the core protocol

XDG-Shell protocol

XDG-Shell protocol is an extended way to manage surfaces under Wayland compositors. The traditional way to manipulate surfaces is to use the wl_shell_* functions, which are part of the core Wayland protocol and live in. An implementation of the xdg-shell protocol, on the contrary, is supposed to be provided by the Wayland compositor. So you will find the header in the Weston source tree.
xdg_shell is a protocol aimed to substitute wl_shell in the long term, but will not be part of the Wayland core protocol. It starts as a non-stable API, aimed to be used as a development place at first, and once features are defined as required by several desktop shells, it can be finally made stable. It provides mainly two new interfaces: xdg_surface and xdg_popup. The xdg_surface interface implements a desktop-style window that can be moved, resized, maximized, etc.; it provides a request for creating child/parent relationship. The xdg_popup interface implements a desktop-style popup/menu; an xdg_popup is always transient for another surface, and also has implicit grab.