Version 5 (modified by Tim Harvey, 2 weeks ago) (diff)

added -platform cmdline arg info

The following information refers to the Gateworks Yocto 2.3 (aka pyro) BSP

Qt for Embedded on Yocto

Since the Qt 5.0 release, Qt no longer contains its own window system (QWS) implementation. For single-process use cases, the Qt Platform Abstraction is a superior solution. Multiple graphical processes can be supported through Wayland.

There are multiple platform plugins that are potentially usable on Embedded Linux systems: EGLFS, LinuxFB, DirectFB, Wayland. The availability of these depend on the configuration of Qt. On many boards eglfs is chosen as the default one. If the default is not suitable, the QT_QPA_PLATFORM environment variable parameter can be used to request another plugin. Alternatively, for quick tests, the -platform command-line can be used with the same syntax.

EGLFS is a platform plugin for running Qt5 applications on top of EGL and OpenGL ES 2.0 without an actual windowing system (like X11 or Wayland). In addition to Qt Quick 2 and native OpenGL applications, it supports software-rendered windows (for example QWidget) too. In the latter case the widgets' contents are rendered using the CPU into images, which are then uploaded into textures and composited by the plugin.

This is the recommended plugin for modern Embedded Linux devices that include a GPU.

EGLFS forces the first top-level window (be it 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 (for example dialogs, popup menus or combobox dropdowns) are composited. This is necessary because with EGLFS there is always exactly one native window and EGL window surface, and 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 entire lifetime of the application and all other widgets are either non top-levels or are created afterwards, once the main window is shown.

For Ventana boards based on the i.MX6 SoC in order to build Qt5 for a specific platform plugin, you must alter the DISTRO_FEATURES variable and remove the backends you don't want. This is typically done in build/local.conf (Note the mandatory space around the options inside the quotes):

  • to build for EGLFS (ie no window system):
    DISTRO_FEATURES_remove = " wayland x11 "
  • for X11 (ie for building an X11 based image like 'gateworks-image-gui')
    DISTRO_FEATURES_remove = " wayland "
  • for Wayland (supports X11 clients but uses Wayland compositor)
    DISTRO_FEATURES_remove = " x11 "

You can specify what backend to use via the '-platform' cmdline argument. For example if you don't have X11 packages installed:

qtglviddemo -platform eglfs

Note that if you remove a DISTRO feature then any package requiring that feature (via REQUIRED_DISTRO_FEATURES in its recipe) will be skipped causing any images/packages depending on or requiring that to fail. For example if you remove x11 you will not be able to build gateworks-image-x11 and if you remove weston you will not be able to build core-image-weston.

QtGLVidDemo Qt5 Demo Application

The qtglvviddemo is a GPLv3 licensed Qt5 demo application for rendering videos on 3D objects integrated in QtQuick 2.

The qtglviddemo demo application shows how to render video frames on 3D objects, which in turn are integrated in a QML and QtQuick 2 based user interface.

The video frames are produced by the GStreamer GstPlayer library. They are uploaded into OpenGL textures, which are then used on 3D meshes. These meshes are rendered in QQuickFramebufferObject QtQuick 2 items, and the items are composed by a PathView on screen. The 3D objects can be rotated with the mouse or with touch events. UI controls allow for adjusting several parameters such as opacity, scale, mesh type, etc. and for adding/removing objects. The video frames can come from local video files, network streams, or Video4Linux2 based video capture devices.

Subtitles can be shown on screen. The subtitles can come either from the playing media itself, or from a FIFO if one is enabled in the configuration file.

There is also special support built in for Vivante GPUs, specifically their direct texture extensions. This makes it possible to render high resolution videos smoothly on i.MX6 machines for example.


  • Qt 5.7 or newer
  • GStreamer 1.10 or newer
  • libudev

Pre-Compiled Yocto Binaries

You can find pre-built binary images for the qtglviddemo-image on the Gateworks ventana/Yocto page.

Once booted you can run with:

qtglviddemo -platform eglfs -c /etc/qtglviddemo.cfg

Any changes you make via the GUI can be saved back the the config file you specified (/etc/qtglvviddemo.cfg) by hitting Save config.


The qtglviddemo application was written as both a demo application and example Qt5 application source demonstrating video rendering on a Gateworks IMX6 board. The project was commissioned by Gateworks and authorred by Carlos Rafael Giani <dv@…>. Carlos is also the author of the gstreamer-imx, a set of GStreamer 1.0 plugins for i.MX6 based products using Freescale's kernel drivers.

The source and documentation is available on github:

Building for Ventana

While the qtglviddemo package can be built from the Gateworks Yocto 2.3 BSP you can also build an entire bootable filesystem image.

There are a couple of choices:

  • X11 based image gateworks-image-gui:
    • includes the matchbox window manager and a host of other X11 based demos
    • requires building the enitre BSP with 'DISTRO_FEATURES_remove = " wayland "' defined in build/local.conf
  • EGLFS based stand-alone app qtglviddemo-image recipe.
    • stand-alone application rendering directly to hardware via EGLFS without any window manager
    • requires building the enitre BSP with 'DISTRO_FEATURES_remove = " wayland x11 "' defined in build/local.conf

For example to build Yocto with the EGLFS backend as you would do with a stand-alone application managing the entire screen:

echo 'DISTRO_FEATURES_remove = " wayland x11 "' >> build/local.conf
bitbake qtglviddemo-image
  • takes about 2 hours or less to build on a modern machine
  • if you have previously built without removing wayland or x11 you need to completely rebuild (ie 'rm -rf tmp')