This article gives information about the Linux® Wayland/Weston framework. It explains how to configure it and, based on examples, how to use it.
1. Framework purpose[edit source]
The Wayland/Weston[1] framework is dedicated to the management of the displays, including the composition[2] of their contents, the support of their related input device events (touchscreen, mouse, keyboard...) and their settings (background wallpapers, resolutions, multi-screens...):
- Wayland[3] is a protocol that specifies the communication between a display server and its clients. Wayland is intended as a simpler replacement for the X Window system[4], easier to develop and maintain.
- Weston is the reference implementation of a Wayland compositor that is a display server using the Wayland protocol. Weston is a minimal and fast compositor and is suitable for many embedded and mobile use cases.
The purpose of this article is to provide a quick overview of the Wayland/Weston framework, giving some hints on how to use and configure Weston and some external references to better understand the Wayland/Weston structure.
2. System overview[edit source]
2.1. Component description[edit source]
From Application/Middleware to Hardware
- Application/Middleware (User space): The Wayland client application or middleware relying on the Wayland protocol. This client can be traditional applications or middleware, X servers (rootless or fullscreen) or other display servers.
- Wayland/Weston (User space): The Wayland libraries implementing the Wayland display server protocol and the Weston libraries using this Wayland protocol for implementing the display server running on the Linux Kernel Mode Setting (KMS), the composition based on OpenGLES and Direct Rendering Manager (DRM) and the management of Linux input devices.
- OpenGLES (User space): The OpenGLES libraries used by Weston for the GPU-based composition.
- libdrm/libkms (User space): The libdrm and libkms libraries are used by the Weston compositor to configure the display path and refresh the display content.
- GPU driver (Kernel space): The Linux kernel driver used to transfer OpenGLES commands to the GPU hardware block.
- DRM/KMS driver (Kernel Space): The DRM/KMS Linux kernel driver to access the display hardware block.
- GPU (Hardware): The GPU hardware block.
- Display (Hardware): The display hardware block.
- LCD device (Hardware): The physical LCD device to display contents.
2.2. API description[edit source]
The Wayland protocol API is described in the official Wayland documentation https://wayland.freedesktop.org/docs/html .
3. Configuration[edit source]
The /etc/xdg/weston/weston.ini file allows the user to set its Weston shell look and behaviour preferences.
In this file you will be able to configure:
- the shell appearance:
- deactivation of the panel bar using panel-location variable
- color of the panel bar using panel-color variable
- background color using background-color variable
- background image using background-image variable
- keyboard layout (qwerty, azerty...) using keymap_layout variable (us, fr...)
- ...
- the animation during transition (to enable if GPU is supported)
- the launcher bar by adding some icons and associated script
- the display output (HDMI, DSI, DVO, LVDS, ...)
Please refer to the Ubuntu weston.ini manpage[5] to know how to configure it.
You may want also to configure:
- the Weston screen resolution: How to configure Weston screen resolution.
- the Weston keyboard layout: How to configure the Weston keyboard layout.
4. How to use the framework[edit source]
4.1. Start Weston[edit source]
Weston is automatically started at boot by systemd using /lib/systemd/system/weston.service.
You can plug a keyboard and a mouse on the board and enjoy the Weston desktop mode.
To start/stop or enable/disable the Weston service, please refer to How to stop and start Weston article.
4.2. Weston utilities[edit source]
Once Weston is started, you can launch simple Wayland client examples.
Here below some interesting utilities...
4.2.1. Display some images[edit source]
weston-image utility decodes and displays in Wayland window image contents:
weston-image <file(s)>
Variety of image types are supported such as jpeg, png or webp. If the image is bigger than display, the image is resized transparently. Several files can be given in argument, one window being opened per file:
weston-image rose-flower-blossom-bloom-39517.jpeg rose-flower-blossom-bloom-39517.jpeg
4.2.2. Embedded terminal[edit source]
weston-terminal opens a new Wayland window with a terminal session. Connect a keyboard and a mouse and you can use your board as an autonomous personal computer.
Start first a Weston terminal session using your PC console:
weston-terminal
Then switch to keyboard connected to board and type:
Wayland Terminal$> weston-image rose-flower-blossom-bloom-39517.jpeg
4.2.3. OpenGLES application[edit source]
weston-simple-egl aims to check that GPU is up & running and well integrated within the Wayland/Weston system. It opens a new alpha transparent Wayland window with a rotating colorized triangle.
weston-simple-egl
has EGL_EXT_buffer_age and EGL_EXT_swap_buffers_with_damage 244 frames in 5 seconds: 48.799999 fps 242 frames in 5 seconds: 48.400002 fps
Other options are available, check usage below:
weston-simple-egl -h
Usage: simple-egl [OPTIONS]
-f Run in fullscreen mode
-o Create an opaque surface
-s Use a 16 bpp EGL config
-b Don't sync to compositor redraw (eglSwapInterval 0)
-h This help text
4.2.4. Make screen or video capture[edit source]
Please refer to the following articles:
4.2.5. List of Weston utilities[edit source]
Client example binaries location:
ls -1 /usr/bin/weston*
/usr/bin/weston /usr/bin/weston-calibrator /usr/bin/weston-clickdot /usr/bin/weston-cliptest /usr/bin/weston-confine /usr/bin/weston-dnd /usr/bin/weston-editor /usr/bin/weston-eventdemo /usr/bin/weston-flower /usr/bin/weston-fullscreen /usr/bin/weston-image /usr/bin/weston-info /usr/bin/weston-launch /usr/bin/weston-multi-resource /usr/bin/weston-presentation-shm /usr/bin/weston-resizor /usr/bin/weston-scaler /usr/bin/weston-simple-damage /usr/bin/weston-simple-dmabuf-v4l /usr/bin/weston-simple-egl /usr/bin/weston-simple-shm /usr/bin/weston-simple-touch /usr/bin/weston-smoke /usr/bin/weston-stacking /usr/bin/weston-start /usr/bin/weston-subsurfaces /usr/bin/weston-terminal /usr/bin/weston-transformed
4.3. Wayland "Hello World"[edit source]
You can find various Wayland "Hello World" applications on internet. We suggest to browse:
- https://jan.newmarch.name/Wayland/index.html (contains EGL, Cairo, GTK, Qt and SDL Wayland examples)
- https://github.com/emersion/hello-wayland
- https://gitlab.com/hdante/hello_wayland
You can refer to the official Wayland documentation: https://wayland.freedesktop.org/docs/html/index.html
5. How to trace and debug the framework[edit source]
To debug weston and enable log traces, please refer to How to debug Weston article.
6. Source code location[edit source]
- Core Wayland protocol source code
- Additional Wayland protocols source code
- Weston compositor source code
7. To go further[edit source]
You can find a good overview of the Wayland/Weston implementation in the Wayland/Weston overview chapter of the presentation held at the 2015 Automotive Linux Summit: Using Linux Media Controller for Wayland/Weston Renderer
You can refer to the official Wayland documentation: https://wayland.freedesktop.org/docs/html/index.html
8. References[edit source]