/****************************************************************************
**
** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
  \page embedded-linux.html
  \title Qt for Embedded Linux

  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 \l{Qt Platform Abstraction} is a superior solution. Multiple
  graphical processes will be supported through Wayland.

  There are multiple platform plugins that are potentially usable on Embedded
  Linux systems: EGLFS, LinuxFB, 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 \c -platform command-line
  parameter can be used to request another plugin.

  \section1 Configuring for a Specific Device

  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 LinuxFB plugin, however neither
  OpenGL nor Qt Quick 2 will be functional in such a setup.

  The directory \e qtbase/mkspecs/devices contains configuration and graphics
  adaptation code for a number of devices. For example, \c linux-rasp-pi-g++
  contains build settings for the \l {http://www.raspberrypi.org}{Raspberry Pi}
  and an implementation of the eglfs hooks (vendor-specific adaptation
  code). This means that the eglfs platform plugin will be automatically built
  with the correct, Raspberry Pi-specific adaptation code. The device is
  selected through the \l{Qt Configure Options}{configure} tool's \c -device
  parameter. The name that follows after this argument must, at least partially,
  match one of the subdirectories under \e devices.

  Below is an example configuration for the Raspberry Pi. For most Embedded
  Linux boards the configure command will look very similar. The most important
  parameters are \c -device and \c -sysroot.

  \code
    ./configure -release -opengl es2 -device linux-rasp-pi-g++ -device-option CROSS_COMPILE=$TOOLCHAIN/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf- -sysroot $ROOTFS -prefix /usr/local/qt5
  \endcode

  See \l {Qt Configure Options} for more information.

  \section1 Platform Plugins for Embedded Linux Devices

  \section2 EGLFS

  \l {http://www.khronos.org/egl}{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: The creation of a \e {native
  window} (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 and
  vendor-specific adaptation code (the so-called \e {eglfs hooks}).

  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 \e 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.

  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 QWindow,
  a QQuickView or a QGLWidget). Opening additional OpenGL windows or mixing such
  windows with QWidget-based content is not supported and will terminate the
  application with an error message.

  If necessary, eglfs can be configured via environment variables:

  \list

  \li \c {QT_QPA_EGLFS_FB} - Overrides the framebuffer device. The default is \c
  /dev/fb0. 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 \c fb
  parameter in LinuxFB.

  \li \c {QT_QPA_EGLFS_WIDTH} and \c {QT_QPA_EGLFS_HEIGHT} - Contain the screen
  width and height in pixels. While eglfs will try to determine the dimensions
  from the framebuffer device \e{/dev/fb0}, this will not always work and
  manually specifying the sizes may become necessary.

  \li \c {QT_QPA_EGLFS_PHYSICAL_WIDTH} and \c {QT_QPA_EGLFS_PHYSICAL_HEIGHT} -
  Physical screen width and height in millimeters. On platforms where the
  framebuffer device \e{/dev/fb0} 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 \c {QT_QPA_EGLFS_DEPTH} - Overrides the color depth for the screen. On
  platforms where the framebuffer device \e{/dev/fb0} 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 QScreen. It has no connection to EGL configurations and the
  color depth used for OpenGL rendering.

  \li \c {QT_QPA_EGLFS_SWAPINTERVAL} - By default a swap interval of \c 1 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 \c {QT_QPA_EGLFS_FORCEVSYNC} - When set, eglfs requests \c
  FBIO_WAITFORVSYNC on the framebuffer device.

  \li \c {QT_QPA_EGLFS_FORCE888} - 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 \c {QT_QPA_EGLFS_DEBUG} - When set, some debugging information is printed
  on the debug output. For example, the input QSurfaceFormat and the properties
  of the chosen EGL configuration are printed whenever creating a new
  context. Together with Qt Quick's \c {QSG_INFO} variable, this can provide
  useful information for troubleshooting issues related to the EGL
  configuration.

  \endlist

  \section2 LinuxFB

  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.

  The \c linuxfb plugin allows specifying additional settings by passing them in
  the \c -platform command-line argument. For example, \c {-platform
  linuxfb:fb=/dev/fb1} specifies that the framebuffer device \c /dev/fb1 should
  be used instead of the default \c fb0. Multiple settings can be specfified by
  separating them with a colon.

  \list

  \li \c {fb=/dev/fbN} - 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 \c{size=}\e{<width>}\c{x}\e{<height>} - 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 \c{mmSize=}\e{<width>}\c{x}\e{<height>} - Physical width and height in
  millimeters.

  \li \c{offset=}\e{<width>}\c{x}\e{<height>} - Offset in pixels specifying the
  top-left corner of the screen. The default position is at \c{(0, 0)}.

  \li \c {nographicsmodeswitch} - Do not switch the virtual terminal to graphics
  mode (\c KD_GRAPHICS). 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 \c {tty=/dev/ttyN} - Overrides the virtual console. Only used when \c
  {nographicsmodeswitch} is not set.

  \endlist

  \section2 KMS

  An experimental platform plugin using kernel modesetting and \l
  {http://dri.freedesktop.org/wiki/DRM}{drm} (Direct Rendering Manager).

  \section1 Input

  When no windowing system is present, the mouse, keyboard and touch input are
  read directly via \c evdev or using helper libraries like \c tslib. Note that
  this requires that devices nodes \c {/dev/input/event*} are readable by the
  user. eglfs has all the evdev input handling code built-in, while linuxfb
  relies on the traditional \c -plugin command-line parameters.

  To enable keyboard, mouse, touch or tablet support with linuxfb, pass \c
  {-plugin evdevkeyboard}, \c {-plugin evdevmouse}, \c{-plugin evdevtouch}, or
  \c {-plugin evdevtablet} on the command-line. Most of these can take a device
  node parameter, for example \c {-plugin evdevmouse:/dev/event1}, in case the
  Qt's automatic device discovery (based either on \e libudev or a walkthrough
  of \c {/dev/input/event*}) is not functional or misbehaving.

  For eglfs, these parameters, like the device node name, can be set in the
  environment variables \c QT_QPA_EVDEV_MOUSE_PARAMETERS, \c
  QT_QPA_EVDEV_KEYBOARD_PARAMETERS and \c
  QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS. Additionally, the built-in input handlers
  can be disabled by setting \c QT_QPA_EGLFS_DISABLE_INPUT to \c 1. On some
  touch screens the coordinates will need to be rotated. This can be enabled by
  setting \c QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS to \c {rotate=180}.

  The mouse cursor will show up whenever \c QT_QPA_EGLFS_HIDECURSOR (for eglfs)
  or \c QT_QPA_FB_HIDECURSOR (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.

  Hot plugging is supported, but only if Qt was configured with libudev support
  (that is, if the \e libudev development headers are present in the sysroot at
  configure time). This allows connecting or disconnecting an input device while
  the application is running. On eglfs the mouse cursor will disappear and
  reappear appropriately.

  EGLFS, LinuxFB and KMS are disabling the terminal keyboard on application
  startup. This prevents keystrokes from going to the terminal \e underneath the
  application. If the old behavior needs to be restored for some reason, set the
  environment variable \c QT_QPA_ENABLE_TERMINAL_KEYBOARD to \c 1. Note that
  this will not work when the application is launched from a remote console (for
  example, via \c ssh) and the terminal keyboard input will remain enabled.

  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 passing \c{-plugin tslib} instead
  of \c evdevtouch. To change the device, set the environment variable \c
  TSLIB_TSDEVICE or pass the device name on the command-line.

  \section1 Platform Plugins for Windowing Systems on Embedded Linux Devices

  \section2 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
  \l {http://xcb.freedesktop.org}{xcb}, this plugin will function just like it
  does on a regular PC desktop.

  \note 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 QWidget
  for example).

  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.

  \section2 Wayland

  \l{http://wayland.freedesktop.org/}{Wayland} is a light-weight windowing
  system; or more precisely, it is a protocol for clients to talk to a display
  server.

  The Qt Wayland module is not currently part of Qt 5. Development snapshots can
  be downloaded from the \l{http://qt.gitorious.org/qt/qtwayland}{Qt Wayland git
  repository}. \note The sources checked out from the repository may have
  dependencies on not-yet-released changes in Qt 5's qtbase and qtdeclarative
  repositories.
*/
