/usr/share/qt5/doc/qtdoc/embedded-linux.html is in qt5-doc-html 5.5.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- emb-linux.qdoc -->
<title>Qt for Embedded Linux | Qt 5.5 </title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li><a href="index.html">Qt 5.5</a></li>
<li>Qt for Embedded Linux</li>
<li id="buildversion">Qt 5.5.1 Reference Documentation</li>
</ul>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#configuring-for-a-specific-device">Configuring for a Specific Device</a></li>
<li class="level1"><a href="#platform-plugins-for-embedded-linux-devices">Platform Plugins for Embedded Linux Devices</a></li>
<li class="level2"><a href="#eglfs">EGLFS</a></li>
<li class="level2"><a href="#linuxfb">LinuxFB</a></li>
<li class="level2"><a href="#kms">KMS</a></li>
<li class="level1"><a href="#input">Input</a></li>
<li class="level2"><a href="#input-on-eglfs-and-linuxfb">Input on eglfs and linuxfb</a></li>
<li class="level2"><a href="#mouse">Mouse</a></li>
<li class="level2"><a href="#keyboard">Keyboard</a></li>
<li class="level2"><a href="#touch">Touch</a></li>
<li class="level2"><a href="#pen-based-tablets">Pen-based tablets</a></li>
<li class="level2"><a href="#using-libinput">Using libinput</a></li>
<li class="level2"><a href="#debugging-input-devices">Debugging Input Devices</a></li>
<li class="level2"><a href="#using-custom-mouse-cursor-images">Using custom mouse cursor images</a></li>
<li class="level1"><a href="#display-output">Display output</a></li>
<li class="level2"><a href="#eglfs">eglfs</a></li>
<li class="level2"><a href="#video-memory">Video Memory</a></li>
<li class="level2"><a href="#linuxfb">linuxfb</a></li>
<li class="level1"><a href="#platform-plugins-for-windowing-systems-on-embedded-linux-devices">Platform Plugins for Windowing Systems on Embedded Linux Devices</a></li>
<li class="level2"><a href="#xcb">XCB</a></li>
<li class="level2"><a href="#wayland">Wayland</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt for Embedded Linux</h1>
<span class="subtitle"></span>
<!-- $$$embedded-linux.html-description -->
<div class="descr"> <a name="details"></a>
<p>With the release of Qt 5.0, Qt no longer contains its own window system implementation: QWS is no longer a supported platform. For single-process use cases, the <a href="qpa.html">Qt Platform Abstraction</a> is a superior solution. Multiple graphical processes will be supported through Wayland.</p>
<p>There are multiple platform plugins that are potentially usable on Embedded Linux systems: EGLFS, <a href="embedded-linux.html#linuxfb">LinuxFB</a>, KMS, DirectFB, Wayland. The availability of these depend on the configuration of Qt. The default platform plugin is also device specific. For instance, on many boards eglfs will be chosen as the default one. If the default is not suitable, the <code>QT_QPA_PLATFORM</code> environment variable parameter can be used to request another plugin. Alternatively, for quick tests, the <code>-platform</code> command-line can be used with the same syntax.</p>
<a name="configuring-for-a-specific-device"></a>
<h2 id="configuring-for-a-specific-device">Configuring for a Specific Device</h2>
<p>Building Qt for a given device requires a toolchain and a sysroot. Additionally, some devices require vendor specific adaptation code for EGL and OpenGL ES 2.0 support. This is not relevant for non-accelerated platforms, for example the ones using the <a href="embedded-linux.html#linuxfb">LinuxFB</a> plugin, however neither OpenGL nor Qt Quick 2 will be functional in such a setup.</p>
<p>The directory <i>qtbase/mkspecs/devices</i> contains configuration and graphics adaptation code for a number of devices. For example, <code>linux-rasp-pi2-g++</code> contains build settings, such as the optimal compiler and linker flags, for the <a href="http://www.raspberrypi.org">Raspberry Pi 2</a>, and either an implementation of the eglfs hooks (vendor-specific adaptation code), or a reference to a suitable eglfs device integration plugin. The device is selected through the <a href="configure-options.html">configure</a> tool's <code>-device</code> parameter. The name that follows after this argument must, at least partially, match one of the subdirectories under <i>devices</i>.</p>
<p>Below is an example configuration for the Raspberry Pi 2. For most Embedded Linux boards the configure command will look very similar.</p>
<pre class="cpp"><span class="operator">.</span><span class="operator">/</span>configure <span class="operator">-</span>release <span class="operator">-</span>opengl es2 <span class="operator">-</span>device linux<span class="operator">-</span>rasp<span class="operator">-</span>pi2<span class="operator">-</span>g<span class="operator">+</span><span class="operator">+</span> <span class="operator">-</span>device<span class="operator">-</span>option CROSS_COMPILE<span class="operator">=</span>$TOOLCHAIN<span class="operator">/</span>arm<span class="operator">-</span>bcm2708<span class="operator">/</span>gcc<span class="operator">-</span>linaro<span class="operator">-</span>arm<span class="operator">-</span>linux<span class="operator">-</span>gnueabihf<span class="operator">-</span>raspbian<span class="operator">/</span>bin<span class="operator">/</span>arm<span class="operator">-</span>linux<span class="operator">-</span>gnueabihf<span class="operator">-</span> <span class="operator">-</span>sysroot $ROOTFS <span class="operator">-</span>prefix <span class="operator">/</span>usr<span class="operator">/</span>local<span class="operator">/</span>qt5</pre>
<p>The most important parameters are <code>-device</code> and <code>-sysroot</code>. By specifying <code>-sysroot</code>, the include files and libraries used by <code>configure</code>'s feature detection tests, as well as Qt itself, will be taken from the specified location, instead of the host PC's standard locations. This means that installing development packages on the host machine has no relevance: for example, to get libinput support it is not sufficient or necessary to have the libinput development headers and libraries installed on the host environment. Instead, the headers and the libraries for the target architecture (e.g. ARM) have to be present in the sysroot.</p>
<p><code>pkg-config</code> is supported also when performing cross-compilation. <code>configure</code> will automatically set <code>PKG_CONFIG_LIBDIR</code> to make <code>pkg-config</code> report compiler and linker settings based on the sysroot instead of the host machine. This will usually function well without any further adjustments. However, environment variables such as <code>PKG_CONFIG_PATH</code> should be unset for the host machine before running <code>configure</code>. Otherwise the Qt build may attempt to use inappropriate headers and libraries from the host system.</p>
<p>See <a href="configure-options.html">Qt Configure Options</a> for more information.</p>
<a name="platform-plugins-for-embedded-linux-devices"></a>
<h2 id="platform-plugins-for-embedded-linux-devices">Platform Plugins for Embedded Linux Devices</h2>
<a name="eglfs"></a>
<h3 >EGLFS</h3>
<p><a href="http://www.khronos.org/egl">EGL</a> 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: The creation of a <i>native window</i> (which will not necessarily be an actual window on the screen) must still be done by platform-specific means. Hence the need for the board or GPU specific adaptation code. Such adaptations are provided either as <i>eglfs hooks</i>, a single source file compiled in to the platform plugin, or as dynamically loaded <i>EGL device integration</i> plugins.</p>
<p>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 <a href="../qtwidgets/qwidget.html">QWidget</a>) 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.</p>
<p>This is the recommended plugin for modern Embedded Linux devices that include a GPU.</p>
<p>EGLFS forces the first top-level window (be it either a <a href="../qtwidgets/qwidget.html">QWidget</a> or a <a href="../qtquick/qquickview.html">QQuickView</a>) to become fullscreen. This window is also chosen to be the <i>root</i> 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.</p>
<p>There are further restrictions for OpenGL-based windows. As of Qt 5.3, eglfs supports a single, fullscreen GL window (for example, an OpenGL-based <a href="../qtgui/qwindow.html">QWindow</a>, a <a href="../qtquick/qquickview.html">QQuickView</a> or a QGLWidget). Opening additional OpenGL windows or mixing such windows with <a href="../qtwidgets/qwidget.html">QWidget</a>-based content is not supported and will terminate the application with an error message.</p>
<p>If necessary, eglfs can be configured via environment variables:</p>
<ul>
<li><code>QT_QPA_EGLFS_FB</code> - Overrides the framebuffer device. The default is <code>/dev/fb0</code>. On most embedded platforms this is not very relevant because the framebuffer is used only for querying settings like the display dimensions. On certain devices however this parameter provides the ability to specify which display to use in multiple display setups, similarly to the <code>fb</code> parameter in <a href="embedded-linux.html#linuxfb">LinuxFB</a>.</li>
<li><code>QT_QPA_EGLFS_WIDTH</code> and <code>QT_QPA_EGLFS_HEIGHT</code> - Contain the screen width and height in pixels. While eglfs will try to determine the dimensions from the framebuffer device <i>/dev/fb0</i>, this will not always work and manually specifying the sizes may become necessary.</li>
<li><code>QT_QPA_EGLFS_PHYSICAL_WIDTH</code> and <code>QT_QPA_EGLFS_PHYSICAL_HEIGHT</code> - Physical screen width and height in millimeters. On platforms where the framebuffer device <i>/dev/fb0</i> is not available or the query is not successful, the values are calculated based on a default DPI of 100. This variable can be used to override any such defaults.</li>
<li><code>QT_QPA_EGLFS_DEPTH</code> - Overrides the color depth for the screen. On platforms where the framebuffer device <i>/dev/fb0</i> is not available or the query is not successful, the default of 32 is used. This variable can be used to override any such defaults. Note that this affects only the color depth value reported by <a href="../qtgui/qscreen.html">QScreen</a>. It has no connection to EGL configurations and the color depth used for OpenGL rendering.</li>
<li><code>QT_QPA_EGLFS_SWAPINTERVAL</code> - By default a swap interval of <code>1</code> will be requested. This enables synchronizing to the displays vertical refresh. The value can be overridden with this environment variable. For instance, passing 0 will disable blocking on swap, resulting in running as fast as possible without any synchronization.</li>
<li><code>QT_QPA_EGLFS_FORCEVSYNC</code> - When set, eglfs requests <code>FBIO_WAITFORVSYNC</code> on the framebuffer device.</li>
<li><code>QT_QPA_EGLFS_FORCE888</code> - When set, the red, green and blue color channel sizes are ignored whenever creating a new context, window or offscreen surface. Instead, the plugin will request a configuration with 8 bits per channel. This can be helpful on devices where configurations with less than 32 or 24 bits per pixel are chosen by default but are known not to be suitable, for example, due to banding effects. Instead of changing all the applications, this variable provides an easier shortcut to force 24/32 bpp configurations for a given device.</li>
<li><code>QT_QPA_EGLFS_DEBUG</code> - When set, some debugging information is printed on the debug output. For example, the input <a href="../qtgui/qsurfaceformat.html">QSurfaceFormat</a> and the properties of the chosen EGL configuration are printed whenever creating a new context. Together with Qt Quick's <code>QSG_INFO</code> variable, this can provide useful information for troubleshooting issues related to the EGL configuration.</li>
<li><code>QT_QPA_EGLFS_INTEGRATION</code> - In addition to the compiled-in <i>hooks</i>, it is also possible to provide device or vendor-specific adaptation in the form of dynamically loaded plugins. This environment variable enforces a specific plugin. For example, setting it to <i>eglfs_kms</i> will use the KMS/DRM backend. This is only an option when no static, compiled-in hooks were specified in the device makespecs. In practice the traditional compiled-in hooks are rarely used, almost all backends are now migrated to plugins. The device makespecs still contain a relevant <code>EGLFS_DEVICE_INTEGRATION</code> entry: the name of the preferred backend for that particular device. This is optional, but very useful to avoid the need to set this environment variable in case there are more than one plugins present in the target system. In a desktop environment the KMS or the X11 backends are prioritized, depending on the presence of the <code>DISPLAY</code> environment variable. Note that on some boards the special value of <code>none</code> will be used instead of an actual plugin. This indicates that no special integration is necessary to use EGL with the framebuffer and so no plugins should be loaded.</li>
</ul>
<p>In addition to <code>QT_QPA_EGLFS_DEBUG</code>, eglfs also supports the more modern categorized logging system of Qt. The following logging categories are available:</p>
<ul>
<li><code>qt.qpa.egldeviceintegration</code> – Enables logging for dynamically loaded backends. Very useful to check what backend is in use.</li>
<li><code>qt.qpa.input</code> – Enables debug output both from the evdev and libinput input handlers. Very useful to check if a given input device was correctly recognized and opened.</li>
<li><code>qt.qpa.eglfs.kms</code> – Enables verbose logging in the KMS/DRM backend.</li>
</ul>
<a name="linuxfb"></a>
<h3 >LinuxFB</h3>
<p>This plugin writes directly to the framebuffer. Only software-rendered content is supported. Note that on some setups the display performance is expected to be limited.</p>
<p>The <code>linuxfb</code> plugin allows specifying additional settings by passing them in the <code>QT_QPA_PLATFORM</code> environment variable or <code>-platform</code> command-line option. For example, <code>QT_QPA_PLATFORM=linuxfb:fb=/dev/fb1</code> specifies that the framebuffer device <code>/dev/fb1</code> should be used instead of the default <code>fb0</code>. Multiple settings can be specfified by separating them with a colon.</p>
<ul>
<li><code>fb=/dev/fbN</code> - Specifies the framebuffer devices. On multiple display setups this will typically allow running the application on different displays. For the time being there is no way to use multiple framebuffers from one Qt application.</li>
<li><code>size=</code><i><width></i><code>x</code><i><height></i> - Specifies the screen size in pixels. The plugin will try to query the display dimensions, both physical and logical, from the framebuffer device. This may not always lead to proper results however, and therefore it may become necessary to explicitly specify the values.</li>
<li><code>mmSize=</code><i><width></i><code>x</code><i><height></i> - Physical width and height in millimeters.</li>
<li><code>offset=</code><i><width></i><code>x</code><i><height></i> - Offset in pixels specifying the top-left corner of the screen. The default position is at <code>(0, 0)</code>.</li>
<li><code>nographicsmodeswitch</code> - Do not switch the virtual terminal to graphics mode (<code>KD_GRAPHICS</code>). In addition to switching to graphics mode, the blinking cursor and screen blanking are normally disabled too. When this parameter is set, these are also skipped.</li>
<li><code>tty=/dev/ttyN</code> - Overrides the virtual console. Only used when <code>nographicsmodeswitch</code> is not set.</li>
</ul>
<a name="kms"></a>
<h3 >KMS</h3>
<p>An experimental platform plugin using kernel modesetting and <a href="http://dri.freedesktop.org/wiki/DRM">drm</a> (Direct Rendering Manager).</p>
<p><b>Note: </b>This plugin is obsolete. eglfs has its own KMS/DRM support which provides all the functionality of the kms plugin and also adds features, like multiple display support, that were not previously available in the standalone plugin. Using the kms plugin is therefore strongly discouraged.</p><a name="input"></a>
<h2 id="input">Input</h2>
<p>When no windowing system is present, the mouse, keyboard and touch input are read directly via <code>evdev</code> or using helper libraries like <code>tslib</code>. Note that this requires that devices nodes <code>/dev/input/event*</code> are readable by the user. eglfs and linuxfb has all the evdev input handling code built-in.</p>
<a name="input-on-eglfs-and-linuxfb"></a>
<h3 >Input on eglfs and linuxfb</h3>
<p>Parameters like the device node name can be set in the environment variables <code>QT_QPA_EVDEV_MOUSE_PARAMETERS</code>, <code>QT_QPA_EVDEV_KEYBOARD_PARAMETERS</code> and <code>QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS</code>. Additionally, the built-in input handlers can be disabled by setting <code>QT_QPA_EGLFS_DISABLE_INPUT</code> or <code>QT_QPA_FB_DISABLE_INPUT</code> to <code>1</code>. On some touch screens the coordinates will need to be rotated. This can be enabled by setting <code>QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS</code> to <code>rotate=180</code>.</p>
<a name="mouse"></a>
<h3 >Mouse</h3>
<p>The mouse cursor will show up whenever <code>QT_QPA_EGLFS_HIDECURSOR</code> (for eglfs) or <code>QT_QPA_FB_HIDECURSOR</code> (for linuxfb) is not set and Qt's libudev-based device discovery reports that at least one mouse is available. When libudev support is not present, the mouse cursor will always show up unless explicitly disabled via the environment variable.</p>
<p>Hot plugging is supported, but only if Qt was configured with libudev support (that is, if the <i>libudev</i> development headers are present in the sysroot at configure time). This allows connecting or disconnecting an input device while the application is running.</p>
<a name="keyboard"></a>
<h3 >Keyboard</h3>
<p>The evdev keyboard handler supports the following extra parameters:</p>
<ul>
<li><code>/dev/input/...</code> - Specifies the name of the input device. When not given, Qt will look for a suitable device either via <i>libudev</i> or by walking through the available nodes.</li>
<li><code>grab</code> - Enables grabbing the input device.</li>
<li><code>keymap</code> - Specifies the name of a custom keyboard map file.</li>
<li><code>enable-compose</code> - Enables compositing.</li>
<li><code>repeat-delay</code> - Sets a custom key repeat delay.</li>
<li><code>repeat-rate</code> - Sets a custom key repeat rate.</li>
</ul>
<p>On Embedded Linux systems that do not have their terminal sessions disabled, the behavior when pressing a key can be confusing due to having the input event processed both by the Qt application and the tty. To overcome this, the following options are available:</p>
<ul>
<li>EGLFS, <a href="embedded-linux.html#linuxfb">LinuxFB</a> and KMS attempt to disable the terminal keyboard on application startup by setting the tty's keyboard mode to <code>K_OFF</code>. This prevents keystrokes from going to the terminal. If the standard behavior needs to be restored for some reason, set the environment variable <code>QT_QPA_ENABLE_TERMINAL_KEYBOARD</code> to <code>1</code>. Note that this will not work when the application is launched from a remote console (for example, via <code>ssh</code>) and the terminal keyboard input will remain enabled.</li>
<li>An alternative approach is to use the evdev keyboard handler's <code>grab</code> parameter by passing <i>grab=1</i> in <code>QT_QPA_EVDEV_KEYBOARD_PARAMETERS</code>. This results in trying to get a grab on the input device which, if successful, means that no other components in the system receive events from it as long as the Qt application is running. This approach is more suitable for applications started remotely as it does not need access to the tty device.</li>
<li>Finally, for many specialized Embedded Linux images it will not make sense to have the standard terminal sessions enabled in the first place. Refer to your build environment's documentation on how to disable them. For example, when generating images using the <a href="http://www.yoctoproject.org">Yocto Project</a>, unsetting <code>SYSVINIT_ENABLED_GETTYS</code> will result in having no <code>getty</code> process running, and thus no input, on any of the virtual terminals.</li>
</ul>
<p>If the default, built-in keymap is not sufficient, a different one can be specified either via the <code>keymap</code> parameter or by using the eglfs-specific <a href="../qtplatformheaders/qeglfsfunctions.html#loadKeymap">loadKeymap()</a> function. The latter allows switching the keymap at runtime. Note however that this requires using eglfs' built-in keyboard handler; it is not supported when the keyboard handler is loaded via the <code>-plugin</code> command-line parameter.</p>
<p><b>Note: </b>Special system key combinations, such as console switching (<i>Ctrl+Alt+Fx</i>) or zap (<i>Ctrl+Alt+Backspace</i>) are not currently supported and will get ignored.</p><p>To generate a custom keymap, the <i>kmap2qmap</i> utility can be used. This can be found in the <i>qttools</i> module. The source files have to be in standard Linux <code>kmap</code> format that is e.g. understood by the kernel's <code>loadkeys</code> command. This means one can use the following sources to generate <code>qmap</code> files:</p>
<ul>
<li>The <a href="http://lct.sourceforge.net/">Linux Console Tools (LCT)</a> project.</li>
<li><a href="http://www.x.org/">Xorg</a> X11 keymaps can be converted to the <code>kmap</code> format with the <code>ckbcomp</code> utility.</li>
<li>As <code>kmap</code> files are plain text files, they can also be hand crafted.</li>
</ul>
<p><code>kmap2qmap</code> is a command line program, that needs at least 2 files as parameters. The last one will be the generated <code>.qmap</code> file, while all the others will be parsed as input <code>.kmap</code> files. For example:</p>
<pre class="cpp">kmap2qmap i386/qwertz/de-latin1-nodeadkeys.kmap include/compose.latin1.inc de-latin1-nodeadkeys.qmap</pre>
<p><b>Note: </b><code>kmap2qmap</code> does not support all the (pseudo) symbols that the Linux kernel supports. When converting a standard keymap, a number of warnings will be shown regarding <code>Show_Registers</code>, <code>Hex_A</code>, and so on; these messages can safely be ignored.</p><a name="touch"></a>
<h3 >Touch</h3>
<p>For some resistive, single-touch touch screens it may be necessary to fall back to using tslib instead of relying on the Linux multitouch protocol and the event devices. For modern touch screens this should not be necessary. tslib support can be enabled by setting the environment variable <code>QT_QPA_EGLFS_TSLIB</code> or <code>QT_QPA_FB_TSLIB</code> to 1. To change the device, set the environment variable <code>TSLIB_TSDEVICE</code> or pass the device name on the command-line. Note that the tslib input handler generates mouse events and supports single touch only, as opposed to evdevtouch which generates true multi-touch <a href="../qtgui/qtouchevent.html">QTouchEvent</a> events too.</p>
<a name="pen-based-tablets"></a>
<h3 >Pen-based tablets</h3>
<p>The <code>evdevtablet</code> plugin provides basic support for Wacom and similar, pen-based tablets. It will only generate <a href="../qtgui/qtabletevent.html">QTabletEvent</a> events. To enable it, pass <code>QT_QPA_GENERIC_PLUGINS=evdevtablet</code> in the environment or, alternatively, <code>-plugin evdevtablet</code> on the command-line. The plugin can take a device node parameter, for example <code>QT_QPA_GENERIC_PLUGINS=evdevtablet:/dev/event1</code>, in case the Qt's automatic device discovery (based either on <i>libudev</i> or a walkthrough of <code>/dev/input/event*</code>) is not functional or misbehaving.</p>
<a name="using-libinput"></a>
<h3 >Using libinput</h3>
<p><a href="http://www.freedesktop.org/wiki/Software/libinput">libinput</a> is a library to handle input devices. It offers an alternative to the default evdev input support. To switch to using libinput, first make sure the development files for libudev and libinput are available when configuring and building Qt. This will result in building the libinput plugin. Then, if using eglfs or linuxfb, disable the built-in input handlers by setting <code>QT_QPA_EGLFS_DISABLE_INPUT</code> or <code>QT_QPA_FB_DISABLE_INPUT</code> to <code>1</code>. Finally, launch the application with <code>-plugin libinput</code>.</p>
<a name="debugging-input-devices"></a>
<h3 >Debugging Input Devices</h3>
<p>It is possible to print some information to the debug output by enabling the <code>qt.qpa.input</code> logging rule, for example by setting the <code>QT_LOGGING_RULES</code> environment variable to <code>qt.qpa.input=true</code>. This is useful for detecting which device is being used, or to troubleshoot device discovery issues.</p>
<a name="using-custom-mouse-cursor-images"></a>
<h3 >Using custom mouse cursor images</h3>
<p>eglfs comes with its own set of 32x32 sized mouse cursor images. If these are not sufficient, a custom cursor atlas can be provided by setting the <code>QT_QPA_EGLFS_CURSOR</code> environment variable to the name of a JSON file. The file can also be embedded into the application via Qt's resource system.</p>
<p>For example, an embedded cursor atlas with 8 cursor images per row can be specified like the following:</p>
<pre class="cpp"> {
"image": ":/cursor-atlas.png",
"cursorsPerRow": 8,
"hotSpots": [
[7, 2],
[12, 3],
[12, 12],
...
]
}</pre>
<p>Note that the images are expected to be tightly packed in the atlas: the width and height of the cursors are decided based on the total image size and the <code>cursorsPerRow</code> setting. Atlases have to provide an image for all the supported cursors.</p>
<a name="display-output"></a>
<h2 id="display-output">Display output</h2>
<p>When having multiple displays connected, the level of support for targeting one or more of these from one single Qt application varies between the platform plugins and often depends on the device and its graphics stack.</p>
<a name="eglfs"></a>
<h3 >eglfs</h3>
<p>When the KMS/DRM backend is in use, eglfs will report all available screens in <a href="../qtgui/qguiapplication.html#screens">QGuiApplication::screens</a>(). Applications can target different screens with different windows via <a href="../qtgui/qwindow.html#setScreen">QWindow::setScreen</a>(). Note however that the restriction of one single fullscreen window per screen still applies.</p>
<p>When getting started with developing on a given embedded device, it is often 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 <code>-platform eglfs --multiscreen --timeout</code> will show a rotating Qt logo on each connected screen for a few seconds.</p>
<p>The KMS/DRM backend also supports custom configurations via a JSON file. Set the environment variable <code>QT_QPA_EGLFS_KMS_CONFIG</code> to the name of the file to enable this. The file can also be embedded in the application via the Qt resource system. An example configuration is below:</p>
<pre class="cpp"> {
"device": "/dev/dri/card1",
"hwcursor": false,
"pbuffers": true,
"outputs": [
{
"name": "VGA1",
"mode": "off"
},
{
"name": "HDMI1",
"mode": "1024x768"
}
]
}</pre>
<p>Here we configure the specified device so that</p>
<ul>
<li>it will not use the hardware cursor (falls back to rendering the mouse cursor via OpenGL; by default hardware cursors are enabled since they are more efficient),</li>
<li>it will back <a href="../qtgui/qoffscreensurface.html">QOffscreenSurface</a> with standard EGL pbuffer surfaces (by default this is disabled and a gbm surface is used instead),</li>
<li>output on the VGA connector is disabled, while HDMI is active with a resolution of 1024x768.</li>
</ul>
<p>Additionally, such a configuration will also disable looking for a device via <code>libudev</code> and instead the specified device will be used.</p>
<p>For troubleshooting it might be useful to enable debug logs from the KMS/DRM backend. To do this, enable the categorized logging rule <code>qt.qpa.eglfs.kms</code>.</p>
<p>Other backends, that are typically based on targeting the framebuffer directly via the vendor's EGL implementation, will usually provide limited or no support for multiple displays. In some cases the <code>QT_QPA_EGLFS_FB</code> environment variable can be used to control which framebuffer to target, similarly to linuxfb. Alternatively, driver-specific environment variables or kernel parameters may also be available to control the used framebuffer. Refer to the embedded board's documentation.</p>
<a name="video-memory"></a>
<h3 >Video Memory</h3>
<p>Systems with a fixed amount of dedicated video memory may need extra care before running Qt application based on Qt Quick or classes like <a href="../qtwidgets/qopenglwidget.html">QOpenGLWidget</a>. 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 therefore 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.</p>
<a name="linuxfb"></a>
<h3 >linuxfb</h3>
<p>Use the <code>fb</code> plugin parameter to specify the framebuffer device to use.</p>
<a name="platform-plugins-for-windowing-systems-on-embedded-linux-devices"></a>
<h2 id="platform-plugins-for-windowing-systems-on-embedded-linux-devices">Platform Plugins for Windowing Systems on Embedded Linux Devices</h2>
<a name="xcb"></a>
<h3 >XCB</h3>
<p>This is the X11 plugin used on regular desktop Linux platforms. In some embedded environments, that provide X and the necessary development files for <a href="http://xcb.freedesktop.org">xcb</a>, this plugin will function just like it does on a regular PC desktop.</p>
<p><b>Note: </b>On some devices there is no EGL and OpenGL support available under X because the EGL implementation is not compatible with Xlib. In this case the XCB plugin will be built without EGL support, meaning that Qt Quick 2 or other OpenGL-based applications will not work with this platform plugin. It can still be used however to run software-rendered applications (based on <a href="../qtwidgets/qwidget.html">QWidget</a> for example).</p><p>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.</p>
<a name="wayland"></a>
<h3 >Wayland</h3>
<p><a href="http://wayland.freedesktop.org/">Wayland</a> is a light-weight windowing system; or more precisely, it is a protocol for clients to talk to a display server.</p>
<p>The Qt Wayland module provides a <code>wayland</code> platform plugin that allows Qt application to connect to a Wayland compositor.</p>
<p><b>Note: </b>Please note that you may experience issues with touch screen input with the <a href="http://wayland.freedesktop.org/">Weston</a> reference compositor. Please refer to the <a href="https://wiki.qt.io/WestonTouchScreenIssues">Qt Wiki</a> for further information.</p></div>
<!-- @@@embedded-linux.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|