One of the primary things Wayland provides is a protocol for communication between applications and the graphics system (referred to in Wayland-speak as clients and the compositor). This protocol consists of commands to show images on the screen, move stuff around on the screen, deal with keyboards and mice, and on and on.
Each command in this protocol can take one or more arguments, such as an X,Y coordinate or a height and width. These arguments can be integers, strings, arrays or a few other types that Wayland defines. One of these allowed types is an enumeration. An enumeration is a set of constant terms in a specific order, for example [ TOP, LEFT, BOTTOM, RIGHT ].
Wayland’s protocol has used the notion of enums for quite some time, but mostly for descriptive purposes. Data was passed back and forth as raw integers; in the C programming language that’s basically all that enums are anyway, so this was adequate for compositors and clients written in C. C doesn’t really enforce enums as a data type separate from integers.
However, as Wayland usage spreads there is a growing interest in writing client applications in Python, Ruby, Java, etc. using binding libraries generated from the Wayland protocol XML file. Many of these languages do, in fact, enforce enums as a data type, so there is a desire to handle enums properly for these languages.
Supporting Enumeration in Wayland
We don’t want to add an entirely new data type for enums, that’d gratuitously break everything already written for Wayland. Fortunately that’s not necessary. Since enums are integers underneath, we add the “enum-ness” as an attribute and thus link it to the correct enum definition.
For example, where before we might have had:
<arg name="edges" type="uint"/>
With Wayland’s new enum support we now have:
<enum name="resize"> <entry name="none" value="0"> <entry name="top" value="1"/> <entry name="bottom" value="2"/> <entry name="left" value="4"/> <entry name="right" value="8"/> </enum> <arg name="edges" type="uint" enum="resize"/>
Notice how we’ve specified the values not as a simple sequence but as multiples of 2. This is a type of enum called a “bitfield”, because the numbers correspond to the specific bits used by the computer to represent the number. Bitfields allow us to efficiently represent combinations of values, so for example the top left edge would be 1 (top) + 4 (left) = 5 (top-left).
We now have the ability to mark these types of enums, to distinguish them from the run of the mill sequential enums. This is done using a new ‘bitfield’ boolean attribute you can specify when defining the enum. So our above example now becomes something like:
<enum name="resize" bitfield="true"> <entry name="none" value="0"/> <entry name="top" value="1"/> <entry name="bottom" value="2"/> <entry name="left" value="4"/> <entry name="top_left" value="5"/> <entry name="bottom_left" value="6"/> <entry name="right" value="8"/> <entry name="top_right" value="9"/> <entry name="bottom_right" value="10"/> </enum> <arg name="edges" type="uint" enum="resize"/>
Bringing Wayland to Wider Audiences
While this new functionality doesn’t really affect Wayland clients that are written in C, the benefit will come in the form of improved type safety in Wayland applications written in higher level languages, which we hope are many! Wayland is approaching a stable-enough state to begin being used in consumer products, and we want to make it available to wider developer audiences. This change should make it easier for people to write applications that use Wayland!