Qt for Embedded Linux

Platform plugins for embedded Linux devices

On Embedded Linux systems, there are multiple platform plugins that you can use: EGLFS, LinuxFB, DirectFB, or Wayland. However, the availability of these plugins depend on how Qt is configured.

EGLFS is the default plugin on many boards. If it's not suitable, use the QT_QPA_PLATFORM environment variable to request another plugin. Alternatively, for quick tests, use the -platform command-line argument with the same syntax.

See Configure an Embedded Linux Device for an overview of configuring Qt for cross-compilation using an Embedded Linux toolchain.

EGLFS

EGL is an interface between OpenGL and the native windowing system. Qt can use EGL for context and surface management, however the API contains no platform-specifics. Creating a native window, which won't necessarily be an actual window on the screen, must still be done by platform-specific means. This is why we need the board or GPU-specific adaptation code. Typically, these adaptations are provided as:

• EGLFS hooks – a single source file compiled into the platform plugin
• EGL device integration – dynamically loaded plugins

EGLFS is a platform plugin for running Qt applications on top of EGL and OpenGL ES 2.0, without an actual windowing system like X11 or Wayland. It is the recommended plugin for modern Embedded Linux devices that include a GPU.

In addition to Qt Quick and native OpenGL applications, EGLFS supports software-rendered windows, like QWidget, too. For QWidget, the widgets' contents are rendered using the CPU into images, which are then uploaded into textures and composited by the plugin.

EGLFS forces the first top-level window - either a QWidget or a QQuickView - to become fullscreen. This window is also chosen to be the root widget window into which all other top-level widgets are composited. For example, dialogs, popup menus, or combo boxes. This behavior is necessary because with EGLFS there is always exactly one native window and one EGL window surface; these belong to the widget or window that is created first. This approach works well when there is a main window that exists for the application's lifetime and all other widgets are either not top-levels or are created afterward, once the main window is shown.

There are further restrictions for OpenGL-based windows. EGLFS supports a single fullscreen GL window (as of Qt 5.3), like OpenGL-based QWindow, a QQuickView, or a QOpenGLWidget. Opening additional OpenGL windows or mixing such windows with QWidget-based content isn't supported; Qt terminates the application with an error message.

Furthermore, APIs designed for desktop platforms or environments with a windowing system, such as Drag and Drop, are not supported on EGLFS.

Environment variables used by EGLFS

If necessary, eglfs can be configured using the following environment variables:

Additionally, the following less commonly used variables are available:

Logging

In addition to QT_QPA_EGLFS_DEBUG, eglfs also supports Qt's modern categorized logging system. The following logging categories are available:

• qt.qpa.egldeviceintegration – Enables logging for dynamically loaded backends. Use this category to check what backend is in use.
• qt.qpa.input – Enables debug output both from the evdev and libinput input handlers. Use this category to check if a given input device was recognized and opened.
• qt.qpa.eglfs.kms – Enables verbose logging in the KMS/DRM backend.

After running configure, make sure to inspect its output. This is the easiest, quickest way to identify whether you have the necessary EGLFS backend, libudev, or libinput enabled. In short, if there's an undesired "no" in your configure output, run:

./configure -v

to turn on the verbose output, so that you can see the compiler and linker invocations for each configure test.

As an example, when targeting the Raspberry Pi with the Broadcom proprietary graphics drivers, the output should contain something like the following:

QPA backends:
EGLFS ................................ yes
EGLFS details:
  EGLFS i.Mx6 ........................ no
  EGLFS i.Mx6 Wayland ................ no
  EGLFS EGLDevice .................... no
  EGLFS GBM .......................... no
  EGLFS Mali ......................... no
  EGLFS Raspberry Pi ................. yes
  EGL on X11 ......................... no

If this is not the case, it's not advisable to proceed further with the build since accelerated graphics won't be functional without the Raspberry Pi-specific backend, even if the rest of Qt compiles successfully.

LinuxFB

This plugin writes directly to the framebuffer via Linux's fbdev subsystem. Only software-rendered content is supported. Note that on some setups the display performance is expected to be limited.

However, since fbdev is being deprecated in the Linux kernel, the DRM dumb buffer support is also available. To use it, set the QT_QPA_FB_DRM environment variable to a non-zero value. When set, provided that dumb buffers are supported by your system, legacy framebuffer devices like /dev/fb0 won't be accessed. Instead, the rendering is set up via the DRM APIs, similar to the eglfs_kms backend in EGLFS. The output is double-buffered and page flipped, providing proper vsync for software-rendered content as well.

Specifying additional settings

The linuxfb plugin allows you to specify additional settings via the QT_QPA_PLATFORM environment variable or -platform command-line option. For example, QT_QPA_PLATFORM=linuxfb:fb=/dev/fb1 specifies that the framebuffer device /dev/fb1 must be used instead of the default fb0. To specify multiple settings, separate the mwith a colon (:).

As of Qt 5.9, the behavior of EGLFS and LinuxFB has been synchronized, with regards to the window sizing policy: the first top-level window is forced to cover the entire screen, with both platform plugins. If this is not desired, set the QT_QPA_FB_FORCE_FULLSCREEN environment variable to 0 to restore the behavior from earlier Qt versions.

Display output

The level of support to target one or more displays from one single Qt application varies between the platform plugins. Support often depends on the device and its graphics stack.

EGLFS with the eglfs_kms backend

When the KMS/DRM backend is in use, EGLFS reports all available screens in QGuiApplication::screens(). Applications can target different screens with different windows via QWindow::setScreen().

When you start developing on a given embedded device, often it's necessary to verify the behavior of the device and drivers, and that the connected displays are working as they should. One easy way is to use the hellowindow example. Launching it with the -platform eglfs --multiscreen --timeout arguments shows a rotating Qt logo on each connected screen for a few seconds.

Custom configuration

The KMS/DRM backend also supports custom configurations via a JSON file. To enable this, set the QT_QPA_EGLFS_KMS_CONFIG environment variable to the name of the file. You can also embed this file into the application via the Qt resource system.

Most of these configuration options apply to all KMS/DRM-based backends, regardless of the buffer management technology (GBM or EGLStreams).

Here's an example configuration:

{
  "device": "/dev/dri/card1",
  "hwcursor": false,
  "pbuffers": true,
  "outputs": [
    {
      "name": "VGA1",
      "mode": "off"
    },
    {
      "name": "HDMI1",
      "mode": "1024x768"
    }
  ]
}

Here we configure the specified device so that:

• It won't use the hardware cursor (falls back to rendering the mouse cursor via OpenGL; by default hardware cursors are enabled as they're more efficient).
• It backs QOffscreenSurface with standard EGL pbuffer surfaces (by default this is disabled and a gbm surface is used instead).
• Output on the VGA connector is disabled, while HDMI is active with a resolution of 1024x768.

Additionally, such a configuration also disables looking for a device via libudev; instead the specified device is used.

When mode is not defined, the system's preferred mode is chosen. The accepted values for mode are: off, current, preferred, skip, widthxheight, widthxheight@vrefresh, or a modeline string.

Specifying current chooses a mode with a resolution that matches the current one. Because mode-setting is done only when the desired mode is actually different from the active one (unless forced via the QT_QPA_EGLFS_ALWAYS_SET_MODE environment variable), this value is useful to preserve the current mode and any content in the planes not touched by Qt.

skip causes the connector for the output to be ignored as if it were disconnected. off is similar, but it changes the mode and turns off the display.

Default behavior

By default, all screens reported by the DRM layer are treated as one big virtual desktop. The mouse cursor implementation takes this into account and moves across the screens as expected. Although not recommended, you can disable the virtual desktop by setting separateScreens to false in the configuration.

By default, the virtual desktop is formed left to right, based on the order of connectors as reported by the system. To change this, set virtualIndex to a value starting from 0.

For example, the following configuration uses the preferred resolution but ensures that the left side of the virtual desktop is the screen connected to the HDMI port; while the right side is the screen connected to the DisplayPort:

{
  "device": "drm-nvdc",
  "outputs": [
    {
      "name": "HDMI1",
      "virtualIndex": 0
    },
    {
      "name": "DP1",
      "virtualIndex": 1
    }
  ]
}

The order of elements in the array is not relevant. Outputs with unspecified virtual indices are placed after the others, with the original order in the DRM connector list preserved.

To create a vertical desktop space (that is, to stack top to bottom instead of left to right), add a virtualDesktopLayout property after device with the value of vertical.

When virtualIndex is not sufficient, the virtualPos property can be used to explicitly specify the top-left position of the screen in question. Taking the previous example and assuming a resolution of 1080p for HDMI1, the following code snippet places a second HDMI-based screen below the first one:

{
   ...
  "outputs": [
    ...
    {
      "name": "HDMI2",
      "virtualPos": "0, 1080"
    }
  ]
}

Automatic physic screen size querying

In some cases, the automatic querying of the physical screen size via DRM may fail. Normally the QT_QPA_EGLFS_PHYSICAL_WIDTH and QT_QPA_EGLFS_PHYSICAL_HEIGHT environment variable would be used to provide the missing values. This is not suitable anymore when multiple screens are present. Instead, use the physicalWidth and physicalHeight properties in the outputs list to specify the sizes in millimeters.

Active outputs and QScreen instances

Each active output from the outputs array corresponds to one QScreen instance reported from QGuiApplication::screens(). By default, the primary screen that QGuiApplication::primaryScreen() reports is the screen that is registered first. If you're not using virtualIndex, this means the decision is based on the DRM connector order. To override this, set the primary property to true on the desired entry in the outputs list.

For example, to ensure the screen corresponding to the VGA output is the primary even when the system happens to report the HDMI one first, do the following:

{
  "device": "/dev/dri/card0",
  "outputs": [
      { "name": "HDMI1" },
      { "name": "VGA1", "mode": "1280x720", "primary": true },
      { "name": "LVDS1", "mode": "off" }
  ]
}

For troubleshooting, it might be useful to enable debug logs from the KMS/DRM backend. To do this, enable the qt.qpa.eglfs.kms categorized logging rule.

A common use case

The most common and best supported use case for a multi-screen setup is to open a dedicated QQuickWindow or QQuickView for each screen. With the default threaded render loop of the Qt Quick scenegraph, each of these windows will get its own dedicated render thread. This is good because the threads can be throttled independently based on vsync, and will not interfere with each other. With the basic loop, this can get problematic, causing animations to degrade.

For example, discovering all connected screens and creating a QQuickView for each of them can be done like this:

int main(int argc, char **argv)
{
    QGuiApplication app(argc, argv);

    QVector<QQuickView *> views;
    for (QScreen *screen : app.screens()) {
        QQuickView *view = new QQuickView;
        view->setScreen(screen);
        view->setResizeMode(QQuickView::SizeRootObjectToView);
        view->setSource(QUrl("qrc:/main.qml"));
        QObject::connect(view->engine(), &QQmlEngine::quit, qGuiApp, &QCoreApplication::quit);
        views.append(view);
        view->showFullScreen();
    }

    int result = app.exec();

    qDeleteAll(views);
    return result;
}

Advanced eglfs_kms features

Cloning (mirroring)

Screen cloning (mirroring) is supported. This is enabled via the clones property:

{
  "device": "/dev/dri/card0",
  "outputs": [
      { "name": "HDMI1", "mode": "1920x1080" },
      { "name": "DP1", "mode": "1920x1080", "clones": "HDMI1" }
 ]
}

In this case, the content on the display connected via DisplayPort will be the same as on the HDMI one. This is ensured by scanning out the same buffer on both.

However, this feature can only work if the resolutions are the same, there are no incompatibilities when it comes to accepted buffer formats, and the application doesn't have any output on the QScreen associated with a clone destination. In practice, the latter means that no QWindow associated with the QScreen in question - DP1 in the example - must ever perform a QOpenGLContext::swapBuffers() operation. It's up to the configuration and the application to ensure these.

Headless mode using DRM render

Headless mode via DRM render nodes is supported. This allows performing GPU compute (OpenGL compute shaders, OpenCL) or off-screen OpenGL rendering without needing DRM master privileges. In this mode, applications can function even when there is already another process outputting to the screen.

Just switching device from /dev/dri/card0 to /dev/dri/renderD128 is futile on its own since there are a number of operations that cannot be performed in headless mode. Therefore, this must be combined with a headless property, for example:

{
    "device": "/dev/dri/renderD128",
    "headless": "1024x768"
}

Keep in mind that windows are still sized to match the - now virtual - screen size, hence the need for specifying a size in the headless property. There is also a lack of vsync-based throttling.

Once enabled, applications have two typical choices to perform off-screen rendering in headless mode:

Use an ordinary window, such as a QOpenGLWindow subclass, targeting the window's default framebuffer, meaning a gbm_surface in practice:

MyOpenGLWindow w;
w.show(); // will not actually show up on screen
w.grabFramebuffer().save("output.png");

Or the typical offscreen approach with an extra FBO:

QOffscreenSurface s;
s.setFormat(ctx.format());
s.create();
ctx.makeCurrent(&s);
QOpenGLFramebufferObject fbo(1024, 768);
fbo.bind();
ctx.functions()->glClearColor(1, 0, 0, 1);
ctx.functions()->glClear(GL_COLOR_BUFFER_BIT);
fbo.toImage().save("output.png");
ctx.doneCurrent();

DRM API selection

KMS/DRM can be used with two different DRM APIs which are legacy and atomic. The main benefit of DRM atomic API is to allow several DRM plane updates within the same renderloop, whereas legacy API would require one plane update per vsync.

Atomic API is useful when your application needs to blend content into overlays keeping all the updates within the same vsync. Still not all devices support this API and it could be unavailable on some older devices. KMS backend will by default use the legacy API, but you can enable the DRM atomic API with QT_QPA_EGLFS_KMS_ATOMIC environment variable set to 1.

Using a smaller framebuffer than screen resolution can also be useful. This is possible with DRM atomic using the size parameter in the JSON file. The example below uses a 1280x720 framebuffer on a 3840x2160 videomode :

{
  "device": "/dev/dri/card0",
  "outputs": [
    { "name": "HDMI1", "mode": "3840x2160", "size": "1280x720", "format": "argb8888" }
  ]
}

EGLFS with an eglfs_kms_egldevice backend

This backend, typically used on Tegra devices, is similar to the KMS/DRM backend mentioned above, except that it relies on the EGLDevice and EGLStream extensions instead of GBM.

For technical details about this approach, check out this presentation.

As of Qt 5.7 this backend shares many of its internal implementation with the GBM-based backend. This means that multiple screens and the advanced configuration via QT_QPA_EGLFS_KMS_CONFIG are supported. Some settings, such as hwcursor and pbuffers are not applicable however.

By default, the backend will automatically choose the correct EGL layer for the default plane of each output. When necessary, this can be overridden by setting the QT_QPA_EGLFS_LAYER_INDEX environment variable to the index of the desired layer. This approach does not currently support multiple outputs, so its usage should be limited to systems with a single screen. To see which layers are available, and to debug potential startup issues, enable the logging category qt.qpa.eglfs.kms.

In some cases, it may be necessary to perform a video mode set on application startup even when the screen reports that the desired resolution is already set. This is normally optimized away, but if the screen stays powered down, try setting the environment variable QT_QPA_EGLFS_ALWAYS_SET_MODE to a non-zero value and relaunch the application.

To configure the behavior of the EGLStream object used by the backend, use the QT_QPA_EGLFS_STREAM_FIFO_LENGTH environment variable. This assumes that KHR_stream_fifo is supported by the target system. By default, the stream operates in mailbox mode. To switch to FIFO mode, set a value of 1 or greater. The value specifies the maximum number of frames the stream can hold.

On some systems it may become necessary to target a specific overlay plane through a pre-defined connector. Just forcing a layer index via QT_QPA_EGLFS_LAYER_INDEX does not perform plane configuration and is therefore not suitable in itself. Instead, in such special scenarios use the QT_QPA_EGLFS_KMS_CONNECTOR_INDEX and QT_QPA_EGLFS_KMS_PLANE_INDEX environment variables. When these are set, only the specified connector and plane will be in use, all other outputs will get ignored. The backend will take care of picking the EGL layer that corresponds to the desired plane, and configuring the plane.

Touch input in systems with multiple screens on KMS/DRM

Touchscreens require additional considerations in multi-display systems because touch events have to be routed to the correct virtual screen, and this requires a correct mapping between touchscreens and display outputs.

The mapping is done via the JSON configuration file specified in QT_QPA_EGLFS_KMS_CONFIG and described in the previous sections. When a touchDevice property is present in an element of the outputs array, the value is treated as a device node and the touch device is associated with the display output in question.

For example, assuming our touchscreen has a device node of /dev/input/event5 and is a touchscreen integrated into the monitor connected via HDMI as the secondary screen, the following configuration ensures correct touch (and synthesized mouse) event translation:

 {
    "device": "drm-nvdc",
    "outputs": [
      {
        "name": "HDMI1",
        "touchDevice": "/dev/input/event5",
        "virtualIndex": 1
      },
      {
        "name": "DP1",
        "virtualIndex": 0
      }
    ]
}

EGLFS with other backends

Other backends, which are typically based on targeting the framebuffer or a composition API directly via the vendor's EGL implementation, usually provide limited or no support for multiple displays. On i.MX6-based boards with Vivante GPUs the QT_QPA_EGLFS_FB environment variable can be used to specify the framebuffer to target, similarly to linuxfb. On the Raspberry Pi the QT_QPA_EGLFS_DISPMANX_ID environment variable can be used to specify the screen to output to. The value corresponds to one of the DISPMANX_ID_ constants, refer to the Dispmanx documentation. Note that these approaches, unlike KMS/DRM, will not typically allow output to multiple screens from the same application. Alternatively, driver-specific environment variables or kernel parameters may also be available as well to control the used framebuffer. Refer to the embedded board's documentation.

Video memory

Systems with a fixed amount of dedicated video memory may need extra care before running Qt applications based on Qt Quick or classes like QOpenGLWidget. The default setting may be insufficient for such applications, especially when they are displayed on a high resolution (for example, full HD) screen. In this case, they may start failing in unexpected ways. It is recommended to ensure that there is at least 128 MB of GPU memory available. For systems that do not have a fixed amount of memory reserved for the GPU, this is not an issue.

linuxfb

Use the fb plugin parameter to specify the framebuffer device to use.

Unix signal handlers

The console-oriented platform plugins like eglfs and linuxfb install signal handlers by default to capture interrupt (SIGINT), suspend and continue (SIGTSTP, SIGCONT) and termination (SIGTERM). This way the keyboard, terminal cursor, and possibly other graphics state can be restored when the application terminates or gets suspended due to kill, or Ctrl+C or Ctrl+Z. (although terminating or suspending via the keyboard is only possible when QT_QPA_ENABLE_TERMINAL_KEYBOARD is set, as outlined above in the Input section). However, in some cases capturing SIGINT can be undesirable as it may conflict with remote debugging for instance. Therefore, the environment variable QT_QPA_NO_SIGNAL_HANDLER is provided to opt-out from all built-in signal handling.

Fonts

Qt normally uses fontconfig to provide access to system fonts. If fontconfig is not available, Qt will fall back to using QBasicFontDatabase. In this case, Qt applications will look for fonts in Qt's lib/fonts directory. Qt will automatically detect pre-rendered fonts and TrueType fonts. This directory can be overridden by setting the QT_QPA_FONTDIR environment variable.

For more information on the supported formats, see Qt for Embedded Linux Fonts.

Platform plugins for windowing systems on embedded Linux devices

XCB

This is the X11 plugin used on regular desktop Linux platforms. In some embedded environments, that provide X and the necessary development files for xcb, this plugin functions just like it does on a regular PC desktop.

As a general rule, the usage of XCB on embedded devices is not advisable. Plugins like eglfs are likely to provide better performance and hardware acceleration.

Wayland

Wayland is a light-weight windowing system; or more precisely, it is a protocol for clients to talk to a display server.

Qt Wayland provides a wayland platform plugin that allows Qt applications to connect to a Wayland compositor.

For more details, see Wayland and Qt.

Performance enhancement guidelines

Use hardware rendering where possible

When performance is critical to your application, avoid the use of Qt modules that rely on software rendering, such as Qt Charts. Prefer modules that rely on hardware rendering instead, where possible.

Follow the best practices for Qt Quick

Follow the Best Practices for QML and Qt Quick, especially with regards to including the QML CMake API, so that qmllint, QML Script Compiler (qmlsc), and the QML Type Compiler (qmltc) are available. In addition, it's preferable to write declarative QML and minimize Javascript. For more information on how using excessive JavaScript may impact performance see QML Performance Considerations And Suggestions.

Use images/textures and shader effects instead of the Canvas QML type

For drawing custom UI elements, use images/textures and Shader Effects. Don't use the QML Canvas type. Shaders require hardware acceleration (GPU).

Use Qt Quick instead of Qt Widgets

With Qt Quick, it's possible to use either hardware-accelerated or software-rendered backends. For complex Uls, using Qt Widgets on embedded targets is not recommended, as it will always use a software backend.

There are trade-offs here:

• Using the QML engine and Qt Quick comes with initial overhead.
• If your UI is very simple and repaints rarely, it may perform faster when implemented using Widgets instead of QML.
• If your UI benefits from animations, smooth scrolling,and scaling, rendering effects, or 3D you need to have GPU acceleration, and thus Qt Quick.

Choose a resolution appropriate for your UI size

You need to be cautious with higher resolutions. Resolutions of 720p and higher may reduce performance.

Use a QML Window type as your application's root element

Use a Window as your application's root element with the application's background color.

The reasoning for this is that a Window component has a color property that has the effect of being a buffer clear. Rendering the background using a full-screen Rectangle as an application's root Item would cause an additional draw call. For some RHI backends this may be the same thing, but there is a difference between a glClear call and drawing a quad. In most cases, a single, opaque image might not have a large performance impact but if you were to use an alpha value in that item's color, you might see a significant performance impact.

Related topics

• Boot to Qt
• Configure an Embedded Linux Device
• Inputs on an Embedded Linux Device