Skip to main content

Overview

Wayland is a set of communications protocols which underpin an increasing number of Linux graphical environments. Like the X protocol that it intends to replace, Wayland includes optional support for tablet input. This guide provides an introduction to the Wayland tablet protocol, presents the protocol's features, and documents its use. Compositor and toolkit developers may find this guide useful for adding tablet support. Application developers interested in tablet support should consult our other guides on GTK+ and Qt, or their toolkit's own documentation.

Wayland​

Wayland defines an object-oriented, client-server protocol. A "Wayland compositor" responds to requests from applications and notifies them of various events. The content and semantics of these messages are defined by "interfaces" which group related functionality together. Only a few interfaces are core to the protocol; others are optional or even compositor-specific. The core interfaces define, for example, how to work with GPU surfaces and be notified of mouse input. Many interfaces are optional, such as xdg_shell (for common desktop interactions) or the tablet protocol. Compositor-specific protocols may be published or private and provide access to special features.

The Wayland compositor is primarily responsible for managing access to graphics and input resources. These resources may be virtual (e.g. for a remote desktop environment) but more often are real hardware. When working with real hardware, libraries like libEGL and libinput handle much of the heavy lifting; the compositor itself keeps track of what applications own which objects and how they may be used. For example, if a client wants to draw a window, it would send a Wayland request to create a new surface. In response, the compositor would use libEGL to allocate a buffer and hand back a reference for the client to draw into. Similarly, if a client wants to be notified of mouse events, it can request a pointer object through the Wayland protocol. In response, the compositor would return back a reference and add it to a list of clients to be notified whenever libinput has an update from the mouse.

Wayland Tablet Protocol​

Tablet input is handled via an optional interface informally known as the "Wayland tablet protocol". This interface was designed in collaboration with other Wayland developers and is published in the "wayland-protocols" repository alongside other optional interfaces. The tablet protocol defines the format of events from tablet tools (e.g. styli) and other physical controls on the tablet surface (e.g. ExpressKeys and Touch Rings). Note that touch input is not part of the tablet protocol. If available, it should be handled via the core wl_pointer or wl_touch interfaces as appropriate. The tablet protocol provides many features which allow applications to make full use of tablet hardware. Some highlights include:

  • High-resolution XY coordinates
  • Tool state information (hover, pressure, tilt, rotation, etc.)
  • Tool identifiers (generic type, unique ID, etc.)
  • Server- and client-managed ExpressKeys & feedback
  • Multi-pen operation from a single seat (e.g. for interactive whiteboards)

Application Development​

Most application authors should rely on their UI toolkit to deliver tablet events. See the Reference page for relevant links. Unless your toolkit has not implemented support for the Wayland tablet protocol (or is missing support for one of its features), there is no sense in re-inventing the wheel. Sharing protocol objects between the toolkit and an application-specific implementation can be tricky and may require clever programming. If you can obtain a wl_display object for use with libwayland-client, it may be possible to use this guide from the point of view of a toolkit developer.

Compositor & Toolkit Development​

Compositor and toolkit developers should have little trouble getting the tablet protocol's more basic features to work by reading the specification. More advanced features may require additional explanation, especially for developers who are not familiar with tablet hardware. The [Basics]../(wayland-basics) page can be used as a companion to the specification, offering supporting information and context. Examining open-source implementations of the protocol may also prove enlightening. See the Reference page for relevant links.

Notices​

As with other other optional protocols, the Wayland tablet protocol may not be implemented by any given compositor or client. Practically speaking, in order for a tablet to work within a Wayland application, both its toolkit and the user's compositor must support the protocol. Tablet events will not be requested without the former, and tablet events will not be delivered without the latter. Because support for the protocol is still spotty at this time, users may discover that their tablet works in one environment but not another — or one application but not another. Compositor and toolkit developers should strive to list support for the Wayland tablet protocol among other top-line features.

It should also be noted that this is not the only option for tablet input under Wayland. Some compositors may opt to use the limited wl_pointer protocol, or develop an alternative protocol of their own. Implementing solutions like these are not recommended. Tablet data requires a richer protocol than wl_pointer can provide, and alternative protocols are unlikely to be widely supported.