--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/platforms/emb-architecture.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,338 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page qt-embedded-architecture.html
+
+ \title Qt for Embedded Linux Architecture
+ \ingroup qt-embedded-linux
+
+ A \l{Qt for Embedded Linux} application requires a server
+ application to be running, or to be the server application itself.
+ Any \l{Qt for Embedded Linux} application can act as the server.
+ When more than one application is running, the subsequent
+ applications connect to the existing server application as clients.
+
+ The server and client processes have different responsibilities:
+ The server process manages pointer handling, character input, and
+ screen output. In addition, the server controls the appearance of
+ the screen cursor and the screen saver. The client process
+ performs all application specific operations.
+
+ The server application is represented by an instance of the
+ QWSServer class, while the client applications are represented by
+ instances of the QWSClient class. On each side, there are several
+ classes performing the various operations.
+
+ \image qt-embedded-architecture2.png
+
+ All system generated events, including keyboard and mouse events,
+ are passed to the server application which then propagates the
+ event to the appropriate client.
+
+ When rendering, the default behavior is for each client to render
+ its widgets into memory while the server is responsible for
+ putting the contents of the memory onto the screen. But when the
+ hardware is known and well defined, as is often the case with
+ software for embedded devices, it may be useful for the clients to
+ manipulate and control the underlying hardware directly.
+ \l{Qt for Embedded Linux} provides two different approaches to
+ achieve this behavior, see the graphics rendering section below for
+ details.
+
+ \tableofcontents
+
+ \section1 Client/Server Communication
+
+ The running applications continuously alter the appearance of the
+ screen by adding and removing widgets. The server maintains
+ information about each top-level window in a corresponding
+ QWSWindow object.
+
+ Whenever the server receives an event, it queries its stack of
+ top-level windows to find the window containing the event's
+ position. Each window can identify the client application that
+ created it, and returns its ID to the server upon
+ request. Finally, the server forwards the event, encapsulated by
+ an instance of the QWSEvent class, to the appropriate client.
+
+ \image qt-embedded-clientservercommunication.png
+
+ If an input method is installed, it is used as a filter between
+ the server and the client application. Derive from the
+ QWSInputMethod class to implement custom input methods, and use
+ the server's \l {QWSServer::}{setCurrentInputMethod()} function to
+ install it. In addition, it is possible to implement global,
+ low-level filters on key events using the
+ QWSServer::KeyboardFilter class; this can be used to implement
+ things like advanced power management suspended from a button
+ without having to filter for it in all applications.
+
+ \table 100%
+ \header \o UNIX Domain Socket
+ \row
+ \o
+
+ \image qt-embedded-client.png
+
+ The server communicates with the client applications over the UNIX
+ domain socket. You can retrieve direct access to all the events a
+ client receives from the server, by reimplementing QApplication's
+ \l {QApplication::}{qwsEventFilter()} function.
+
+ \endtable
+
+ The clients (and the server) communicate with each other using the
+ QCopChannel class. QCOP is a many-to-many communication protocol
+ for transferring messages on various channels. A channel is
+ identified by a name, and anyone who wants to can listen to
+ it. The QCOP protocol allows clients to communicate both within
+ the same address space and between different processes.
+
+ \section1 Pointer Handling Layer
+
+ \list
+ \o QWSMouseHandler
+ \o QMouseDriverPlugin
+ \o QMouseDriverFactory
+ \endlist
+
+ The mouse driver (represented by an instance of the
+ QWSMouseHandler class) is loaded by the server application when it
+ starts running, using Qt's \l {How to Create Qt Plugins}{plugin
+ system}.
+
+ \image qt-embedded-pointerhandlinglayer.png
+
+ A mouse driver receives mouse events from the device and
+ encapsulates each event with an instance of the QWSEvent class
+ which it then passes to the server.
+
+ \l{Qt for Embedded Linux} provides ready-made drivers for several mouse
+ protocols, see the \l{Qt for Embedded Linux Pointer Handling}{pointer
+ handling} documentation for details. Custom mouse drivers can be
+ implemented by subclassing the QWSMouseHandler class and creating
+ a mouse driver plugin. The default implementation of the
+ QMouseDriverFactory class will automatically detect the plugin,
+ loading the driver into the server application at runtime.
+
+ In addition to the generic mouse handler, \l{Qt for Embedded Linux}
+ provides a calibrated mouse handler. Use the
+ QWSCalibratedMouseHandler class as the base class when the system
+ device does not have a fixed mapping between device and screen
+ coordinates and/or produces noisy events, e.g. a touchscreen.
+
+ See also: \l{Qt for Embedded Linux Pointer Handling} and
+ \l{How to Create Qt Plugins}.
+
+ \section1 Character Input Layer
+
+ \list
+ \o QWSKeyboardHandler
+ \o QKbdDriverPlugin
+ \o QKbdDriverFactory
+ \endlist
+
+ The keyboard driver (represented by an instance of the
+ QWSKeyboardHandler class) is loaded by the server application when
+ it starts running, using Qt's \l {How to Create Qt Plugins}{plugin
+ system}.
+
+ \image qt-embedded-characterinputlayer.png
+
+ A keyboard driver receives keyboard events from the device and
+ encapsulates each event with an instance of the QWSEvent class
+ which it then passes to the server.
+
+ \l{Qt for Embedded Linux} provides ready-made drivers for several keyboard
+ protocols, see the \l {Qt for Embedded Linux Character Input}{character
+ input} documentation for details. Custom keyboard drivers can be
+ implemented by subclassing the QWSKeyboardHandler class and
+ creating a keyboard driver plugin. The default implementation of the
+ QKbdDriverFactory class will automatically detect the plugin, loading the
+ driver into the server application at run-time.
+
+ See also: \l{Qt for Embedded Linux Character Input} and \l {How to Create
+ Qt Plugins}.
+
+ \section1 Graphics Rendering
+
+ \list
+ \o QApplication
+ \o QDecoration
+ \o QDecorationPlugin
+ \o QDecorationFactory
+ \endlist
+
+ The default behavior is for each client to render its widgets as well
+ as its decorations into memory, while the server copies the memory content
+ to the device's framebuffer.
+
+ Whenever a client receives an event that alters any of its
+ widgets, the application updates the relevant parts of its memory
+ buffer:
+
+ \image qt-embedded-clientrendering.png
+
+ The decoration is loaded by the client application when it starts
+ running (using Qt's \l {How to Create Qt Plugins}{plugin system}),
+ and can be customized by deriving from the QDecoration class and
+ creating a decoration plugin. The default implementation of
+ the QDecorationFactory class will automatically detect the plugin,
+ loading the decoration into the application at runtime. Call the
+ QApplication::qwsSetDecoration() function to actually apply the
+ given decoration to an application.
+
+ \table 100%
+ \header \o Direct Painting \target Direct Painting
+ \row
+ \o
+
+ It is possible for the clients to manipulate and control the
+ underlying hardware directly. There are two ways of achieving
+ this: The first approach is to set the Qt::WA_PaintOnScreen window
+ attribute for each widget, the other is to use the QDirectPainter
+ class to reserve a region of the framebuffer.
+
+ \image qt-embedded-setwindowattribute.png
+
+ By setting the Qt::WA_PaintOnScreen attribute, the application
+ renders the widget directly onto the screen and the affected
+ region will not be modified by the screen driver \e unless another
+ window with a higher focus requests (parts of) the same
+ region. Note that if you want to render all of an application's
+ widgets directly on screen, it might be easier to set the
+ QT_ONSCREEN_PAINT environment variable.
+
+ \image qt-embedded-reserveregion.png
+
+ Using QDirectPainter, on the other hand, provides a complete
+ control over the reserved region, i.e., the screen driver will
+ never modify the given region.
+
+ To draw on a region reserved by a QDirectPainter instance, the
+ application must get hold of a pointer to the framebuffer. In
+ general, a pointer to the framebuffer can be retrieved using the
+ QDirectPainter::frameBuffer() function. But note that if the
+ current screen has subscreens, you must query the screen driver
+ instead to identify the correct subscreen. A pointer to the
+ current screen driver can always be retrieved using the static
+ QScreen::instance() function. Then use QScreen's \l
+ {QScreen::}{subScreenIndexAt()} and \l {QScreen::}{subScreens()}
+ functions to access the correct subscreen, and the subscreen's \l
+ {QScreen::}{base()} function to retrieve a pointer to the
+ framebuffer.
+
+ Note that \l{Qt for Embedded Linux} also provides the QWSEmbedWidget class,
+ making it possible to embed the reserved region (i.e., the
+ QDirectPainter object) in a regular widget.
+
+ \endtable
+
+ \section1 Drawing on Screen
+
+ \list
+ \o QScreen
+ \o QScreenDriverPlugin
+ \o QScreenDriverFactory
+ \endlist
+
+ When a screen update is required, the server runs through all the
+ top-level windows that intersect with the region that is about to
+ be updated, and ensures that the associated clients have updated
+ their memory buffer. Then the server uses the screen driver
+ (represented by an instance of the QScreen class) to copy the
+ content of the memory to the screen.
+
+ The screen driver is loaded by the server application when it
+ starts running, using Qt's plugin system. \l{Qt for Embedded Linux}
+ provides ready-made drivers for several screen protocols, see the
+ \l{Qt for Embedded Linux Display Management}{display management}
+ documentation for details. Custom screen drivers can be
+ implemented by subclassing the QScreen class and creating a screen
+ driver plugin. The default implementation of the QScreenDriverFactory
+ class will automatically detect the plugin, loading the driver into
+ the server application at run-time.
+
+ \image qt-embedded-drawingonscreen.png
+
+ To locate the relevant parts of memory, the driver is provided
+ with the list of top-level windows that intersect with the given
+ region. Associated with each of the top-level windows there is an
+ instance of the QWSWindowSurface class representing the drawing
+ area of the window. The driver uses these objects to retrieve
+ pointers to the various memory blocks. Finally, the screen driver
+ composes the surface images before copying the updated region to
+ the framebuffer.
+
+ \table 100%
+ \header \o Accelerated Graphics
+ \row
+ \o
+
+ In \l{Qt for Embedded Linux}, painting is a pure software implementation,
+ but (starting with Qt 4.2) it is possible to add an accelerated
+ graphics driver to take advantage of available hardware resources.
+
+ \image qt-embedded-accelerateddriver.png
+
+ The clients render each window onto a corresponding window surface
+ object using Qt's paint system, and then store the surface in
+ memory. The screen driver accesses the memory and composes the
+ surface images before it copies them to the screen as explained
+ above.
+
+ To add an accelerated graphics driver you must create a custom
+ screen and implement a custom raster paint engine
+ (\l{Qt for Embedded Linux} uses a raster-based paint engine to
+ implement the painting operations). Then you must create a custom
+ paint device that is aware of your paint engine, a custom window
+ surface that knows about your paint device, and make your screen
+ able to recognize your window surface.
+
+ See the \l{Adding an Accelerated Graphics Driver to Qt for Embedded Linux}
+ {accelerated graphics driver} documentation for details.
+
+ \endtable
+
+ See also: \l{Qt for Embedded Linux Display Management} and
+ \l{How to Create Qt Plugins}.
+*/