doc/src/examples/dbscreen.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example qws/dbscreen
  30     \title Double Buffered Graphics Driver Example
  31
  32     \brief The Double Buffered Graphics Driver example shows how to write your own
  33     double buffered graphics driver and add it to Qt for Embedded Linux.
  34
  35     Similar to the \l{Accelerated Graphics Driver Example}, there are three steps
  36     to writing and implementing this graphics driver:
  37
  38     \list 1
  39         \o \l {Step 1: Creating a Custom Graphics Driver}
  40         {Creating a Custom Graphics Driver}
  41
  42         \o \l {Step 2: Implementing the Back Buffer}
  43         {Implementing the Back Buffer}
  44
  45         \o \l {Step 3: Creating the Driver Plugin}
  46         {Creating the Driver Plugin}
  47
  48     \endlist
  49
  50     After compiling the example code, install the graphics driver plugin with
  51     the command \c {make install}. To start an application using the graphics
  52     driver, you can either set the environment variable \l QWS_DISPLAY and
  53     then run the application, or you can just run the application using the
  54     \c -display switch.
  55
  56     Note that this is a minimal example and this driver will not work well
  57     with widgets painting themself directly to the screen (e.g. widgets with
  58     the Qt::WA_PaintOnScreen window attribute set). Also, the example requires
  59     the Linux framebuffer to be set up correctly and with the correct device
  60     permissions. For further information, refer to
  61     \l{Testing the Linux Framebuffer}.
  62
  63     \section1 Step 1: Creating a Custom Graphics Driver
  64
  65     Usually, a custom graphics driver is created by subclassing the QScreen
  66     class, the base class for implementing screen or graphics drivers in
  67     Qt for Embedded Linux. In this example, however, we subclass the QLinuxFbScreen
  68     class instead, to ensure that our driver uses the Linux framebuffer.
  69
  70     For our graphics driver, the \c DBScreen class, we reimplement five
  71     functions belonging to QScreen:
  72
  73     \list
  74         \o \l{QScreen::initDevice()}{initDevice()},
  75         \o \l{QScreen::shutdownDevice()}{shutdownDevice()},
  76         \o \l{QScreen::blit()}{blit()},
  77         \o \l{QScreen::solidFill()}{solidFill()}, and
  78         \o \l{QScreen::exposeRegion()}{exposeRegion()}.
  79     \endlist
  80
  81     \snippet examples/qws/dbscreen/dbscreen.h 0
  82
  83     In addition to the abovementioned functions, there is a private instance
  84     of QPainter and QImage - \c painter, used for drawing operations on
  85     the back buffer, and \c image, the back buffer itself.
  86
  87     \section1 Step 2: Implementing the Back Buffer
  88
  89     The graphics driver must carry out three main functions:
  90
  91     \list 1
  92         \o Allocate the back buffer on startup and deallocate it on shutdown.
  93         \o Draw to the back buffer instead of directly to the screen
  94            (which is what QLinuxFbScreen does).
  95         \o Copy the back buffer to the screen whenever a screen update is
  96            done.
  97     \endlist
  98
  99     \section2 Device initializing and shutdown
 100
 101     We first reimplement \c initDevice() and \c shutdownDevice().
 102
 103     The \c initDevice() function initializes the framebuffer. We reimplement
 104     this function to enable accelerated drivers to set up the graphic card.
 105     For this example, we first call the super class' implementation to set up
 106     the Linux framebuffer. If this call returns \c false, we return \c false.
 107     Otherwise, we initialize the screen cursor with
 108     QScreenCursor::initSoftwareCursor() as well as instantiate \c image and
 109     \c painter. Then, we return \c true.
 110
 111     \snippet examples/qws/dbscreen/dbscreen.cpp 0
 112
 113     The \c shutdownDevice() function's default implementation only hides the
 114     mouse cursor. Hence, we reimplement it to carry out the necessary cleanup
 115     before the Qt for Embedded Linux server exits.
 116
 117     \snippet examples/qws/dbscreen/dbscreen.cpp 1
 118
 119     Again, we call the super class implementation to shutdown the Linux
 120     framebuffer prior to deleting \c image and \c painter.
 121
 122     \section2 Drawing to the back buffer
 123
 124     We move on to the drawing functions - \c solidFill() and \c blit(). In
 125     QLinuxFbScreen, these functions draw directly to the Linux framebuffer;
 126     but in our driver we reimplement them to draw to the back buffer instead.
 127
 128     \snippet examples/qws/dbscreen/dbscreen.cpp 2
 129
 130     The \c solidFill() function is called from \c exposeRegion() to fill the
 131     given \c region of the screen with the specified \c color. In this
 132     example, we use \c painter to fill rectangles in \c image, the back
 133     buffer, according to the given region.
 134
 135     \snippet examples/qws/dbscreen/dbscreen.cpp 3
 136
 137     The \c blit() function is also called from \c exposeRegion() to copy the
 138     given QRegion object, \c region, in the given QImage object, \c image, to
 139     the QPoint object specified by \c topLeft. Once again we use \c painter
 140     to draw in the back buffer, \c image.
 141
 142     \section2 Displaying the buffer on the screen
 143
 144     The \c exposeRegion() function is called by the Qt for Embedded Linux server
 145     whenever a screen update is required. The given \c region is the screen
 146     region that needs to be updated and \c changing is is the index into
 147     QWSServer::clientWindows() of the window that caused the update.
 148
 149     \snippet examples/qws/dbscreen/dbscreen.cpp 4
 150
 151     In our implementation, we first call the super class implementation to
 152     ensure that \c solidFill() and \c blit() will be called correctly. This
 153     causes the changed areas to be updated in the back buffer. We then call
 154     the super class' implementation of \c blit() to copy the updated region
 155     from the back buffer into the Linux framebuffer.
 156
 157     \section1 Step 3: Creating the Driver Plugin
 158
 159     Qt provides a high level API for writing Qt extentions. One of the plugin
 160     base classes provided is QScreenDriverPlugin, which we use in this example
 161     to create our screen driver plugin.
 162
 163     \snippet examples/qws/dbscreen/dbscreendriverplugin.cpp 0
 164
 165     There are only two functions to reimplement:
 166
 167     \list
 168         \o \l{QScreenDriverPlugin::create()}{create()} - creates a driver
 169            matching the given key
 170         \o \l{QScreenDriverPlugin::create()}{keys()} - returns a list of
 171            valid keys representing the drivers supported by the plugin
 172     \endlist
 173
 174     \snippet examples/qws/dbscreen/dbscreendriverplugin.cpp 1
 175     \codeline
 176     \snippet examples/qws/dbscreen/dbscreendriverplugin.cpp 2
 177
 178     Our plugin will only support one driver, \c dbscreen.
 179
 180     Lastly, we export the plugin.
 181
 182     \snippet examples/qws/dbscreen/dbscreendriverplugin.cpp 3
 183
 184     For detailed information about the Qt plugin system see
 185     \l{How to Create Qt Plugins.}
 186 */