1. Description
  2. Running
  3. Debug messages and logging
  4. Building
  5. QPA native interface


1. Description
--------------

  QtUbuntu contains a QPA (Qt Platform Abstraction) plugin based on the Ubuntu
  Platform API and Mir client API


2 Running
---------

  Considering the QPA plugin path is correctly set using either the
  QT_QPA_PLATFORM_PLUGIN_PATH environment variable or the
  "-platformpluginpath" command line switch, the following commands
  can be used to run with the Ubuntu QPA plugin:

    $ qmlscene -platform ubuntumirclient Foo.qml
    $ QT_QPA_PLATFORM=ubuntumirclient qmlscene Foo.qml

  This QPA plugin exposes the following environment variables:

    QT_QPA_EGLFS_SWAPINTERVAL: Specifies the required swap interval as an
                               integer. 1 by default.

    QTUBUNTU_NO_THREADED_OPENGL: Disables QtQuick threaded OpenGL
                                 rendering.

    QTUBUNTU_NO_INPUT: Disables touchscreen and buttons.

    QTUBUNTU_ICON_THEME: Specifies the default icon theme name.


3 Debug messages and logging
----------------------------

  QtUbuntu uses Qt logging categories (see QLoggingCategory class documentation
  for more information). By default warnings and critical messages are
  logged and debug messages are disabled. QtUbuntu provides the following
  logging categories:

  * qt.qpa.mirclient.cursor      - Messages about the cursor.
  * qt.qpa.mirclient.input       - Messages related to input and other Mir events.
  * qt.qpa.mirclient.graphics    - Messages related to graphics, GL and EGL.
  * qt.qpa.mirclient.swapBuffers - Messages related to surface buffer swapping.
  * qt.qpa.mirclient             - For all other messages form the ubuntumirclient QPA.
  * ubuntuappmenu.registrar      - Messages related to application menu registration.
  * ubuntuappmenu                - For all other messages form the ubuntuappmenu QPA theme.

  The QT_QPA_EGLFS_DEBUG environment variable prints a little more information
  from Qt's internals.

4. Building
-----------

  To compile QtUbuntu, create the makefiles with qmake and build with
  make:

    $ qmake
    $ make

  By default, QtUbuntu compiles a release build. To compile a debug
  build, the following qmake command should be used:

    $ qmake CONFIG+=debug


5. QPA native interface
-----------------------

  The QPA plugin exposes a native interface allowing to retrieve
  native handles and to filter out native events. In order to retrieve
  native handles, the following code can be used:

    #include <QtGui/QGuiApplication>
    #include <qpa/qplatformnativeinterface.h>
    ...
    QQuickView* view = new QQuickView();
    ...
    QPlatformNativeInterface* native = QGuiApplication::platformNativeInterface();
    printf("app: eglcontext=%p egldisplay=%p\n",
           native->nativeResourceForContext("eglcontext", view->openglContext()),
           native->nativeResourceForWindow("egldisplay", view));

  Note that handles aren't valid until the application mainloop is started. The
  qmake .pro needs to add private gui include directories using

    QT += gui-private

  Some events exposed in the input compatibility layer can't be
  directly mapped to Qt. In order to retrieve such events, a native
  event filter needs to be installed. To do so, a
  QAbstractNativeEventFilter [1] filtering out "Event" events needs to
  be implemented and installed using
  QCoreApplication::installNativeEventFilter [2].

  [1] http://doc-snapshot.qt-project.org/5.0/qabstractnativeeventfilter.html
  [2] http://doc-snapshot.qt-project.org/5.0/qcoreapplication.html#installNativeEventFilter