1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \page qt-embedded-architecture.html

    44 

    45     \title Qt for Embedded Linux Architecture

    46     \ingroup qt-embedded-linux

    47 

    48     A \l{Qt for Embedded Linux} application requires a server

    49     application to be running, or to be the server application itself.

    50     Any \l{Qt for Embedded Linux} application can act as the server.

    51     When more than one application is running, the subsequent

    52     applications connect to the existing server application as clients.

    53 

    54     The server and client processes have different responsibilities:

    55     The server process manages pointer handling, character input, and

    56     screen output. In addition, the server controls the appearance of

    57     the screen cursor and the screen saver. The client process

    58     performs all application specific operations.

    59 

    60     The server application is represented by an instance of the

    61     QWSServer class, while the client applications are represented by

    62     instances of the QWSClient class. On each side, there are several

    63     classes performing the various operations.

    64 

    65     \image qt-embedded-architecture2.png

    66 

    67     All system generated events, including keyboard and mouse events,

    68     are passed to the server application which then propagates the

    69     event to the appropriate client.

    70 

    71     When rendering, the default behavior is for each client to render

    72     its widgets into memory while the server is responsible for

    73     putting the contents of the memory onto the screen. But when the

    74     hardware is known and well defined, as is often the case with

    75     software for embedded devices, it may be useful for the clients to

    76     manipulate and control the underlying hardware directly.

    77     \l{Qt for Embedded Linux} provides two different approaches to

    78     achieve this behavior, see the graphics rendering section below for

    79     details.

    80 

    81     \tableofcontents

    82 

    83     \section1 Client/Server Communication

    84 

    85     The running applications continuously alter the appearance of the

    86     screen by adding and removing widgets. The server maintains

    87     information about each top-level window in a corresponding

    88     QWSWindow object.

    89 

    90     Whenever the server receives an event, it queries its stack of

    91     top-level windows to find the window containing the event's

    92     position. Each window can identify the client application that

    93     created it, and returns its ID to the server upon

    94     request. Finally, the server forwards the event, encapsulated by

    95     an instance of the QWSEvent class, to the appropriate client.

    96 

    97     \image qt-embedded-clientservercommunication.png

    98 

    99     If an input method is installed, it is used as a filter between

   100     the server and the client application. Derive from the

   101     QWSInputMethod class to implement custom input methods, and use

   102     the server's \l {QWSServer::}{setCurrentInputMethod()} function to

   103     install it. In addition, it is possible to implement global,

   104     low-level filters on key events using the

   105     QWSServer::KeyboardFilter class; this can be used to implement

   106     things like advanced power management suspended from a button

   107     without having to filter for it in all applications.

   108 

   109     \table 100%

   110     \header \o UNIX Domain Socket

   111     \row

   112     \o

   113 

   114     \image qt-embedded-client.png

   115 

   116     The server communicates with the client applications over the UNIX

   117     domain socket. You can retrieve direct access to all the events a

   118     client receives from the server, by reimplementing QApplication's

   119     \l {QApplication::}{qwsEventFilter()} function.

   120 

   121     \endtable

   122 

   123     The clients (and the server) communicate with each other using the

   124     QCopChannel class. QCOP is a many-to-many communication protocol

   125     for transferring messages on various channels. A channel is

   126     identified by a name, and anyone who wants to can listen to

   127     it. The QCOP protocol allows clients to communicate both within

   128     the same address space and between different processes.

   129 

   130     \section1 Pointer Handling Layer

   131 

   132     \list

   133         \o QWSMouseHandler

   134         \o QMouseDriverPlugin

   135         \o QMouseDriverFactory

   136     \endlist

   137 

   138     The mouse driver (represented by an instance of the

   139     QWSMouseHandler class) is loaded by the server application when it

   140     starts running, using Qt's \l {How to Create Qt Plugins}{plugin

   141     system}.

   142 

   143     \image qt-embedded-pointerhandlinglayer.png

   144 

   145     A mouse driver receives mouse events from the device and

   146     encapsulates each event with an instance of the QWSEvent class

   147     which it then passes to the server.

   148 

   149     \l{Qt for Embedded Linux} provides ready-made drivers for several mouse

   150     protocols, see the \l{Qt for Embedded Linux Pointer Handling}{pointer

   151     handling} documentation for details. Custom mouse drivers can be

   152     implemented by subclassing the QWSMouseHandler class and creating

   153     a mouse driver plugin. The default implementation of the

   154     QMouseDriverFactory class will automatically detect the plugin,

   155     loading the driver into the server application at runtime.

   156 

   157     In addition to the generic mouse handler, \l{Qt for Embedded Linux}

   158     provides a calibrated mouse handler. Use the

   159     QWSCalibratedMouseHandler class as the base class when the system

   160     device does not have a fixed mapping between device and screen

   161     coordinates and/or produces noisy events, e.g. a touchscreen.

   162 

   163     See also: \l{Qt for Embedded Linux Pointer Handling} and

   164     \l{How to Create Qt Plugins}.

   165 

   166     \section1 Character Input Layer

   167 

   168     \list

   169         \o QWSKeyboardHandler

   170         \o QKbdDriverPlugin

   171         \o QKbdDriverFactory

   172     \endlist

   173 

   174     The keyboard driver (represented by an instance of the

   175     QWSKeyboardHandler class) is loaded by the server application when

   176     it starts running, using Qt's \l {How to Create Qt Plugins}{plugin

   177     system}.

   178 

   179     \image qt-embedded-characterinputlayer.png

   180 

   181     A keyboard driver receives keyboard events from the device and

   182     encapsulates each event with an instance of the QWSEvent class

   183     which it then passes to the server.

   184 

   185     \l{Qt for Embedded Linux} provides ready-made drivers for several keyboard

   186     protocols, see the \l {Qt for Embedded Linux Character Input}{character

   187     input} documentation for details. Custom keyboard drivers can be

   188     implemented by subclassing the QWSKeyboardHandler class and

   189     creating a keyboard driver plugin. The default implementation of the

   190     QKbdDriverFactory class will automatically detect the plugin, loading the

   191     driver into the server application at run-time.

   192 

   193     See also: \l{Qt for Embedded Linux Character Input} and \l {How to Create

   194     Qt Plugins}.

   195 

   196     \section1  Graphics Rendering

   197 

   198     \list

   199         \o QApplication

   200         \o QDecoration

   201         \o QDecorationPlugin

   202         \o QDecorationFactory

   203     \endlist

   204 

   205     The default behavior is for each client to render its widgets as well

   206     as its decorations into memory, while the server copies the memory content

   207     to the device's framebuffer.

   208 

   209     Whenever a client receives an event that alters any of its

   210     widgets, the application updates the relevant parts of its memory

   211     buffer:

   212 

   213     \image qt-embedded-clientrendering.png

   214 

   215     The decoration is loaded by the client application when it starts

   216     running (using Qt's \l {How to Create Qt Plugins}{plugin system}),

   217     and can be customized by deriving from the QDecoration class and

   218     creating a decoration plugin. The default implementation of

   219     the QDecorationFactory class will automatically detect the plugin,

   220     loading the decoration into the application at runtime. Call the

   221     QApplication::qwsSetDecoration() function to actually apply the

   222     given decoration to an application.

   223 

   224     \table 100%

   225     \header \o Direct Painting \target Direct Painting

   226     \row

   227     \o

   228 

   229     It is possible for the clients to manipulate and control the

   230     underlying hardware directly. There are two ways of achieving

   231     this: The first approach is to set the Qt::WA_PaintOnScreen window

   232     attribute for each widget, the other is to use the QDirectPainter

   233     class to reserve a region of the framebuffer.

   234 

   235     \image qt-embedded-setwindowattribute.png

   236 

   237     By setting the Qt::WA_PaintOnScreen attribute, the application

   238     renders the widget directly onto the screen and the affected

   239     region will not be modified by the screen driver \e unless another

   240     window with a higher focus requests (parts of) the same

   241     region. Note that if you want to render all of an application's

   242     widgets directly on screen, it might be easier to set the

   243     QT_ONSCREEN_PAINT environment variable.

   244 

   245     \image qt-embedded-reserveregion.png

   246 

   247     Using QDirectPainter, on the other hand, provides a complete

   248     control over the reserved region, i.e., the screen driver will

   249     never modify the given region.

   250 

   251     To draw on a region reserved by a QDirectPainter instance, the

   252     application must get hold of a pointer to the framebuffer. In

   253     general, a pointer to the framebuffer can be retrieved using the

   254     QDirectPainter::frameBuffer() function. But note that if the

   255     current screen has subscreens, you must query the screen driver

   256     instead to identify the correct subscreen. A pointer to the

   257     current screen driver can always be retrieved using the static

   258     QScreen::instance() function. Then use QScreen's \l

   259     {QScreen::}{subScreenIndexAt()} and \l {QScreen::}{subScreens()}

   260     functions to access the correct subscreen, and the subscreen's \l

   261     {QScreen::}{base()} function to retrieve a pointer to the

   262     framebuffer.

   263 

   264     Note that \l{Qt for Embedded Linux} also provides the QWSEmbedWidget class,

   265     making it possible to embed the reserved region (i.e., the

   266     QDirectPainter object) in a regular widget.

   267 

   268     \endtable

   269 

   270     \section1 Drawing on Screen

   271 

   272     \list

   273         \o QScreen

   274         \o QScreenDriverPlugin

   275         \o QScreenDriverFactory

   276     \endlist

   277 

   278     When a screen update is required, the server runs through all the

   279     top-level windows that intersect with the region that is about to

   280     be updated, and ensures that the associated clients have updated

   281     their memory buffer. Then the server uses the screen driver

   282     (represented by an instance of the QScreen class) to copy the

   283     content of the memory to the screen.

   284 

   285     The screen driver is loaded by the server application when it

   286     starts running, using Qt's plugin system. \l{Qt for Embedded Linux}

   287     provides ready-made drivers for several screen protocols, see the

   288     \l{Qt for Embedded Linux Display Management}{display management}

   289     documentation for details. Custom screen drivers can be

   290     implemented by subclassing the QScreen class and creating a screen

   291     driver plugin. The default implementation of the QScreenDriverFactory

   292     class will automatically detect the plugin, loading the driver into

   293     the server application at run-time.

   294 

   295     \image qt-embedded-drawingonscreen.png

   296 

   297     To locate the relevant parts of memory, the driver is provided

   298     with the list of top-level windows that intersect with the given

   299     region. Associated with each of the top-level windows there is an

   300     instance of the QWSWindowSurface class representing the drawing

   301     area of the window. The driver uses these objects to retrieve

   302     pointers to the various memory blocks. Finally, the screen driver

   303     composes the surface images before copying the updated region to

   304     the framebuffer.

   305 

   306     \table 100%

   307     \header \o Accelerated Graphics

   308     \row

   309     \o

   310 

   311     In \l{Qt for Embedded Linux}, painting is a pure software implementation,

   312     but (starting with Qt 4.2) it is possible to add an accelerated

   313     graphics driver to take advantage of available hardware resources.

   314 

   315     \image qt-embedded-accelerateddriver.png

   316 

   317     The clients render each window onto a corresponding window surface

   318     object using Qt's paint system, and then store the surface in

   319     memory. The screen driver accesses the memory and composes the

   320     surface images before it copies them to the screen as explained

   321     above.

   322 

   323     To add an accelerated graphics driver you must create a custom

   324     screen and implement a custom raster paint engine

   325     (\l{Qt for Embedded Linux} uses a raster-based paint engine to

   326     implement the painting operations). Then you must create a custom

   327     paint device that is aware of your paint engine, a custom window

   328     surface that knows about your paint device, and make your screen

   329     able to recognize your window surface.

   330 

   331     See the \l{Adding an Accelerated Graphics Driver to Qt for Embedded Linux}

   332     {accelerated graphics driver} documentation for details.

   333 

   334     \endtable

   335 

   336     See also: \l{Qt for Embedded Linux Display Management} and

   337     \l{How to Create Qt Plugins}.

   338 */