An update on libinput

Libinput is a library that provides shared input device (e.g. mouse, keyboard, touchpad) handling for Wayland compositors, as well as providing a generic input driver for the X.Org server. It is a relatively new part of the graphics stack and has just made its 1.0 release on August 26. Peter Hutterer gave an update on libinput at the X.Org Developers Conference (XDC) in Toronto on September 16.

He noted that libinput was introduced roughly a year ago. It is now in use by Weston, but also by GNOME and KDE, as well as X (by using the xf86-input-libinput wrapper driver). Libinput is "pretty much feature complete" at this point and provides all of the functionality that was available for X, plus some extras. It is installed by default in Fedora 22 and later, which led to a lot of bugs landing in his inbox for hardware that had not been tested. Those bugs have been addressed at this point, so libinput is now pretty stable.

He put up a laundry list of features that have been added since XDC2014; "you don't need to remember them, there won't be a test later". For the curious, though, his slides and a YouTube video of the talk are available. He would give more detail on many of those features later in the talk. One of the most important additions is a lot of documentation, he said.

udev

Libinput is now a heavy user of udev. Originally, udev was mostly just used for device discovery, but the input developers decided that if the input stack was to be fixed, it should be done at the right level, which means using udev.

That is bad news for the BSDs (which don't support udev), he said, but it makes it much easier for libinput. The udev hardware database (hwdb) is now a hard requirement, though it would be possible to emulate it in those environments that do not support it. Beyond device discovery, udev is mostly used by libinput to store device attributes via the udev rules that are shipped with it.

The type of a device—whether it is a mouse or keyboard, for example—is determined by udev. That makes for a single place in the system that manages the device types. One advantage of using udev is that custom rules can be used to override that decision. For example, the libwacom project maintains a database of Wacom tablets, along with custom rules to identify them as tablets to udev. Otherwise, tablets can look like various other kinds of devices (e.g. touchpad, pointer) based on the attributes they report.

Some of the attributes that are being stored in udev are pointer acceleration constants such as MOUSE_DPI (which maps device units to millimeters, despite the name) and two for the pointing sticks that come with Lenovo laptops (POINTINGSTICK_SENSITIVITY and POINTINGSTICK_CONST_ACCEL). The idea is to normalize the pointing sticks on different laptop models so they all feel the same out of the box. It is an attempt to find a "blurry middle" between the sticks that are too fast and others that are almost unresponsive as shipped.

The attributes stored in udev are strictly used internally by libinput and cannot be relied on, so they do not constitute an external API. The udev rules that ship with libinput also contain information about device models and attributes of the hardware (e.g. size and resolution). That allows devices with quirks to be identified and handled specially. Udev provides a central runtime storage location so that an attribute can be put into the database and other processes can read it out, he said.

New features

Hutterer then moved on to the new features in libinput, starting with "device groups". There are devices, such as mice for gaming or tablets, that act like multiple input devices (buttons, pointing, keys, etc.). It is "handy to know" if they are all attached to the same physical device, which is what device groups do.

All of the touchpad-handling code has moved to using millimeters. There is also some standardization in their handling. For example, movement of 2mm or less is considered "normal wobble" and does not generate events. All touchpads must have both x and y resolution, and there is a default size (69x50mm) defined for touchpad devices where the actual size is unknown.

The pointer-acceleration algorithm has been tuned, he said. It was "messy to begin with", but is now stable. There is a different mechanism for low-DPI devices (less than 1000 DPI), which are typically older mice. Pointer acceleration is also handled differently for touchpads and trackpoints. There is lots of information (including graphs) on how pointer acceleration is applied in the documentation.

A "flat" acceleration profile that simply applies a constant factor, which is mostly targeted at mice with switchable DPI settings, will also be available. That code was merged quite recently and will be available in libinput 1.1, which is due "soonish".

Touchpad gestures also have good documentation with diagrams of the gestures and information on what kinds of events are generated. For a "swipe", libinput reports a logical center, number of fingers, and changes in the x and y values of the center. Similarly, "pinch" gestures (which also support rotation) report the delta of the logical center, number of fingers, finger "spread factor", and rotation in degrees, though there is no way to use that information in the Wayland protocol as yet.

There is a slight bias toward scrolling for gestures, but the 2mm "dead zone" can make a big difference for small scrolling gestures (e.g. a 5mm scroll). Until the fingers move at least 2mm, it is difficult to determine whether it is a swipe or a pinch/rotate, so that is a problem area right now. Gestures have to be disabled for some touchpads that only have one-finger resolution or other quirks that make it impossible to detect the finger locations precisely enough.

Detecting a thumb resting at the bottom of the touchpad, which can be used to click a "button", is working pretty well. The idea is that the resting thumb is not considered part of any gestures going on elsewhere in the touchpad. In theory, the detection is based on the area and the pressure applied, but some touchpads don't provide enough information. Typically, touchpads detect pressure by the surface size (which increases as more pressure is applied), but thumbs resting at the bottom of the pad are often partially off the pad, which can interfere with the pressure detection.

The source of a scroll event is also reported now. If the scroll comes from a mouse wheel, a finger, or some other continuous scrolling source (like holding down a button and moving the pointing stick), that information is provided to the client. A "scroll end" event is reported as well, which allows clients to implement kinetic scrolling. Neither libinput or the driver implement kinetic scrolling, as it should be done on a per-widget basis, he said.

The X driver

The xf86-input-libinput driver is a thin wrapper around libinput that has "almost no logic". It simply sits between libinput and the X server, delivering events over the X interface. There are only two features implemented in the driver: button drag lock and horizontal scrolling.

Button drag lock is an accessibility feature that allows buttons to be logically down even when they have been physically released. They are considered to be up when the button is pressed again. Ideally that should be handled by the compositor, but X has no compositor to do it, so it is done in the driver.

Libinput always provides horizontal scroll events. Those events should be handled at the widget level, he said, but that is not going to happen in X anytime soon. So there is an option in the driver to discard the horizontal scroll events.

Future plans

For the future, there are several features being planned. Support for Wacom tablets is high on that list. The project has been talking about that support "for a year now". The patches are getting close to being merged at this point.

Adding support for "buttonset" devices, which have buttons and other controls but don't move the pointer, is also planned. Various devices fall into this category, including 3D mice and some tablets. There are more pointer-acceleration improvements coming, as well, mainly for touchpads and trackpoints. Finally, there is a patch pending to provide more information on touch events. Right now, these events only give x and y data, but the patch would add pressure information (area of contact, essentially) and the orientation of the touch.

Hutterer's talk gave a nice look at some of the intricacies of dealing with the wide variety of input devices available these days. Collecting all of that handling in one place and normalizing it, as libinput has done, seems like quite an accomplishment.

[I would like to thank the X.Org Foundation for travel assistance to Toronto for XDC.]