Skip to content

Samples: Graphical applications

These samples show how to customize Welma to run a graphical application at start-up. It can be used to experiment with Welma and as a starting point for your own application and distribution.

The meta-demo-graphics repository contains demonstration images running Qt5 and Qt6 Cinematic Experience application with different graphical compositors: x11, wayland and eglfs (referred as COMPOSITIOR below).

Each of these demonstration projects has its dedicated Yocto layer:

  • meta-demo-qt5-eglfs
  • meta-demo-qt5-wayland
  • meta-demo-qt5-x11
  • meta-demo-qt6-eglfs
  • meta-demo-qt6-wayland

We do not support these on all machines. The following combinations have been tested.

MACHINE                  meta-demo-...
----------------------------------------------------------------------------
de-next-rap8-x86
hbjc386f951t-x86
imx8mm-cgt-sx8m-rev-a
k393x-mini-x86
maaxboard-8ulp-welma
qemuarm-welma                      qt5-wayland qt5-x11 qt6-eglfs qt6-wayland
raspberrypi4-64-welma    qt5-eglfs qt5-wayland qt5-x11           qt6-wayland
sm2s-imx8plus-mbep5                qt5-wayland                   qt6-wayland
sm2s-imx93-mbep5
stm32mp15-disco-welma    qt5-eglfs qt5-wayland         qt6-eglfs qt6-wayland
stm32mp25-disco-welma              qt5-wayland                   qt6-wayland
tungsten-700-smarc-welma           qt5-wayland                   qt6-wayland

Running the demo

We assume here that your environment was already setup from the Quick start guide. The meta-demo-graphics folder should be accessible in your project to continue.

Configure the build

You can use the templates provided to easily set up the build environment. The example below assumes building the meta-demo-qt6-wayland demo.

Warning

This will override your local configuration and changes you made to your local configuration files.

source meta-welma/setup/setup-build-env \
    meta-welma-*/conf/templates/$MACHINE \
    meta-demo-graphics/meta-demo-qt6-wayland/conf/templates/default

The images should now be a available to build from for your machine:

bitbake-layers show-recipes "demo-image-*"

=== Matching recipes: ===
demo-image-qt6-wayland:
  meta-demo-qt6-wayland 1.0
demo-image-qt6-wayland-dbg:
  meta-demo-qt6-wayland 1.0
demo-image-qt6-wayland-dev:
  meta-demo-qt6-wayland 1.0

Build and run

Build the target image:

bitbake demo-image-qt6-wayland-dev

After deploying it on your device or emulator, you should see the Qt application and cinematic experience on the display: Congratulations 🎉!

You can now experiment with your own application, dive into the implementation below, or look at the Next steps.

meta-demo-graphics content

For each of the demo layer:

  • DISTRO and MACHINE are defined in conf/templates/${MACHINE}/local.conf.sample.

  • The bitbake layers are defined in conf/templates/${MACHINE}/bblayers.conf.sample

  • The production image inherits welma-image and adds the demo graphical application:

recipes-welma/images/welma-image-qt5-COMPOSITOR.bb
inherit welma-image

IMAGE_INSTALL += "qt-cinematic-experience"
...

SYSTEMD_DEFAULT_TARGET = "graphical.target"
  • The development image adds developer tools inherited from Welma's development image:
recipes-welma/images/welma-image-qt5-COMPOSITOR-dev.bb
require welma-image-qt5-COMPOSITOR.bb
inherit welma-image-devel

Refresher on Display Protocols

X11

X was built to be a platform-independent graphical system. It is based on the client-server model. The X Client is a front-end software window isolated from the server. When it starts, it connects to the X Server which manages the client. The X Client is able to draw simple forms like rectangles and to display some text, but it cannot draw more elaborate forms like buttons. This will be done by a GUI toolkit. The X Server is responsible for graphical card access and inputs/outputs. It is usually started by a display manager such as GDM. The Xlib library is the client side implementation used by GUI toolkit such as GTK to show an enhanced graphical application. It uses the low level library XCB. Moreover, X11 is the protocol delivering messages between an X Client and an X Server. It allows to run the client and the server on the same machine. The Compositors Overlay Window (COW) provide off-screen buffer for each X Client. It contains the styling and geometry information for their respective client.

Wayland

Wayland is more recent than X11. So it is lighter, it has more security and it is more adapted to work on modern display technologies. Wayland is the protocol that applications can use to communicate with the display server. A Wayland server is a compositor, there is no common server like it was the case with the X11 protocol. Each application is a client and brings its own compositor. Every application using Wayland makes call to the library Libwayland which implements the Wayland protocol to draw effects like transparency, transition animations or blurring. The library codes and decodes Wayland messages. Also, Wayland call a DRM (Direct Rendering Manager) buffer in the kernel to draw things. Steps are simpler and leads to greater performance for graphical applications. It is also easier for the developers to create applications which runs under this protocol.

EGLFS

EGL is an interface between OpenGL and the native windowing system. Qt is able to use EGL for context and surface management, even if it is not specific to platforms. But creating a native window must be done by platform-specific means, so specific adaptation code for the board or the GPU is needed. These adaptations can be provided by EGLFS hooks which are single source file compiled into the platform plugin or EGL device integration which are dynamically loaded plugins. So, EGLFS is a platform plugin which can run Qt applications on top of EGL and OpenGL ES 2.0, without an actual windowing system like X11 or Wayland. It is recommended to use this plugin for modern Embedded Linux devices that include a GPU.

Next steps

You can continue by: