Long live Qt 4.5!

1 files changed, 360 insertions, 0 deletions

diff --git a/doc/src/examples/svgalib.qdoc b/doc/src/examples/svgalib.qdoc
new file mode 100644
index 0000000..c94d408
--- /dev/null
+++ b/doc/src/examples/svgalib.qdoc
@@ -0,0 +1,360 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example qws/svgalib
+    \title Accelerated Graphics Driver Example
+
+    The Accelerated Graphics Driver example shows how you can write
+    your own accelerated graphics driver and \l {add your graphics
+    driver to Qt for Embedded Linux}.  In \l{Qt for Embedded Linux},
+    painting is a pure software implementation and is normally performed
+    in two steps:
+    The clients render each window onto a corresponding surface
+    (stored in memory) using a paint engine, and then the server uses
+    the graphics driver to compose the surface images and copy them to
+    the screen. (See the \l{Qt for Embedded Linux Architecture} documentation
+    for details.)
+
+    The rendering can be accelerated in two ways: Either by
+    accelerating the copying of pixels to the screen, or by
+    accelerating the explicit painting operations. The first is done
+    in the graphics driver implementation, the latter is performed by
+    the paint engine implementation. Typically, both the pixel copying
+    and the painting operations are accelerated using the following
+    approach:
+
+    \list 1
+        \o \l {Step 1: Creating a Custom Graphics Driver}
+        {Creating a Custom Graphics Driver}
+
+        \o \l {Step 2: Implementing a Custom Raster Paint Engine}
+        {Implementing a Custom Paint Engine}
+
+        \o \l {Step 3: Making the Widgets Aware of the Custom Paint
+        Engine}{Making the Widgets Aware of the Custom Paint Engine}
+
+    \endlist
+
+    After compiling the example code, install the graphics driver
+    plugin with the command \c {make install}. To start an application
+    using the graphics driver, you can either set the environment
+    variable \l QWS_DISPLAY and then run the application, or you can
+    just run the application using the \c -display switch:
+
+    \snippet doc/src/snippets/code/doc_src_examples_svgalib.qdoc 0
+
+    \table
+    \header \o SVGAlib
+    \row \o
+
+    Instead of interfacing the graphics hardware directly, this
+    example relies on \l {http://www.svgalib.org}{SVGAlib} being
+    installed on your system.  \l {http://www.svgalib.org}{SVGAlib} is
+    a small graphics library which provides acceleration for many
+    common graphics cards used on desktop computers. It should work on
+    most workstations and has a small and simple API.
+
+    \endtable
+
+    \section1 Step 1: Creating a Custom Graphics Driver
+
+    The custom graphics driver is created by deriving from the QScreen
+    class. QScreen is the base class for implementing screen/graphics
+    drivers in Qt for Embedded Linux.
+
+    \snippet examples/qws/svgalib/svgalibscreen.h 0
+    \codeline
+    \snippet examples/qws/svgalib/svgalibscreen.h 1
+
+    The \l {QScreen::}{connect()}, \l {QScreen::}{disconnect()}, \l
+    {QScreen::}{initDevice()} and \l {QScreen::}{shutdownDevice()}
+    functions are declared as pure virtual functions in QScreen and
+    must be implemented. They are used to configure the hardware, or
+    query its configuration: \l {QScreen::}{connect()} and \l
+    {QScreen::}{disconnect()} are called by both the server and client
+    processes, while the \l {QScreen::}{initDevice()} and \l
+    {QScreen::}{shutdownDevice()} functions are only called by the
+    server process.
+
+    QScreen's \l {QScreen::}{setMode()} and \l {QScreen::}{blank()}
+    functions are also pure virtual, but our driver's implementations
+    are trivial. The last two functions (\l {QScreen::}{blit()} and \l
+    {QScreen::}{solidFill()}) are the ones involved in putting pixels
+    on the screen, i.e., we reimplement these functions to perform the
+    pixel copying acceleration.
+
+    Finally, the \c context variable is a pointer to a \l
+    {http://www.svgalib.org}{SVGAlib} specific type. Note that the
+    details of using the \l {http://www.svgalib.org}{SVGAlib} library
+    is beyond the scope of this example.
+
+    \section2 SvgalibScreen Class Implementation
+
+    The \l {QScreen::}{connect()} function is the first function that
+    is called after the constructor returns. It queries \l
+    {http://www.svgalib.org}{SVGAlib} about the graphics mode and
+    initializes the variables.
+
+    \snippet examples/qws/svgalib/svgalibscreen.cpp 0
+
+    It is important that the \l {QScreen::}{connect()} function
+    initializes the \c data, \c lstep, \c w, \c h, \c dw, \c dh, \c d,
+    \c physWidth and \c physHeight variables (inherited from QScreen)
+    to ensure that the driver is in a state consistent with the driver
+    configuration.
+
+    In this particular example we do not have any information of the
+    real physical size of the screen, so we set these values with the
+    assumption of a screen with 72 DPI.
+
+    \snippet examples/qws/svgalib/svgalibscreen.cpp 1
+
+    When the \l {QScreen::}{connect()} function returns, the server
+    process calls the \l {QScreen::}{initDevice()} function which is
+    expected to do the necessary hardware initialization, leaving the
+    hardware in a state consistent with the driver configuration.
+
+    Note that we have chosen to use the software cursor. If you want
+    to use a hardware cursor, you should create a subclass of
+    QScreenCursor, create an instance of it, and make the global
+    variable \c qt_screencursor point to this instance.
+
+    \snippet examples/qws/svgalib/svgalibscreen.cpp 2
+    \codeline
+    \snippet examples/qws/svgalib/svgalibscreen.cpp 3
+
+    Before exiting, the server process will call the \l
+    {QScreen::}{shutdownDevice()} function to do the necessary
+    hardware cleanup. Again, it is important that the function leaves
+    the hardware in a state consistent with the driver
+    configuration. When \l {QScreen::}{shutdownDevice()} returns, the
+    \l {QScreen::}{disconnect()} function is called. Our
+    implementation of the latter function is trivial.
+
+    Note that, provided that the \c QScreen::data variable points to a
+    valid linear framebuffer, the graphics driver is fully functional
+    as a simple screen driver at this point. The rest of this example
+    will show where to take advantage of the accelerated capabilities
+    available on the hardware.
+
+    Whenever an area on the screen needs to be updated, the server will
+    call the \l {QScreen::}{exposeRegion()} function that paints the 
+    given region on screen. The default implementation will do the 
+    necessary composing of the top-level windows and call \l 
+    {QScreen::}{solidFill()} and \l {QScreen::}{blit()} whenever it is 
+    required. We do not want to change this behavior in the driver so
+    we do not reimplement \l {QScreen::}{exposeRegion()}. 
+
+    To control how the pixels are put onto the screen we need to
+    reimplement the \l {QScreen::}{solidFill()} and \l 
+    {QScreen::}{blit()} functions.
+
+    \snippet examples/qws/svgalib/svgalibscreen.cpp 4
+    \codeline
+    \snippet examples/qws/svgalib/svgalibscreen.cpp 5
+
+    \section1 Step 2: Implementing a Custom Raster Paint Engine
+
+    \l{Qt for Embedded Linux} uses QRasterPaintEngine (a raster-based
+    implementation of QPaintEngine) to implement the painting
+    operations.
+
+    Acceleration of the painting operations is done by deriving from
+    QRasterPaintEngine class. This is a powerful mechanism for
+    accelerating graphic primitives while getting software fallbacks
+    for all the primitives you do not accelerate.
+
+    \snippet examples/qws/svgalib/svgalibpaintengine.h 0
+
+    In this example, we will only accelerate one of the \l
+    {QRasterPaintEngine::}{drawRects()} functions, i.e., only
+    non-rotated, aliased and opaque rectangles will be rendered using
+    accelerated painting. All other primitives are rendered using the
+    base class's unaccelerated implementation.
+
+    The paint engine's state is stored in the private member
+    variables, and we reimplement the \l
+    {QPaintEngine::}{updateState()} function to ensure that our
+    custom paint engine's state is updated properly whenever it is
+    required. The private \c setClip() and \c updateClip() functions
+    are only helper function used to simplify the \l
+    {QPaintEngine::}{updateState()} implementation.
+
+    We also reimplement QRasterPaintEngine's \l
+    {QRasterPaintEngine::}{begin()} and \l
+    {QRasterPaintEngine::}{end()} functions to initialize the paint
+    engine and to do the cleanup when we are done rendering,
+    respectively.
+
+    \table
+    \header \o Private Header Files
+    \row
+    \o
+
+    Note the \c include statement used by this class. The files
+    prefixed with \c private/ are private headers file within
+    \l{Qt for Embedded Linux}. Private header files are not part of
+    the standard installation and are only present while
+    compiling Qt. To be able to compile using
+    private header files you need to use a \c qmake binary within a
+    compiled \l{Qt for Embedded Linux} package.
+
+    \warning Private header files may change without notice between
+    releases.
+
+    \endtable
+
+    The \l {QRasterPaintEngine::}{begin()} function initializes the
+    internal state of the paint engine. Note that it also calls the
+    base class implementation to initialize the parts inherited from
+    QRasterPaintEngine:
+
+    \snippet examples/qws/svgalib/svgalibpaintengine.cpp 0
+    \codeline
+    \snippet examples/qws/svgalib/svgalibpaintengine.cpp 1
+
+    The implementation of the \l {QRasterPaintEngine::}{end()}
+    function removes the clipping constraints that might have been set
+    in \l {http://www.svgalib.org}{SVGAlib}, before calling the
+    corresponding base class implementation.
+
+    \snippet examples/qws/svgalib/svgalibpaintengine.cpp 2
+
+    The \l {QPaintEngine::}{updateState()} function updates our
+    custom paint engine's state. The QPaintEngineState class provides
+    information about the active paint engine's current state.
+
+    Note that we only accept and save the current matrix if it doesn't
+    do any shearing. The pen is accepted if it is opaque and only one
+    pixel wide. The rest of the engine's properties are updated
+    following the same pattern. Again it is important that the
+    QPaintEngine::updateState() function is called to update the
+    parts inherited from the base class.
+
+    \snippet examples/qws/svgalib/svgalibpaintengine.cpp 3
+    \codeline
+    \snippet examples/qws/svgalib/svgalibpaintengine.cpp 4
+
+    The \c setClip() helper function is called from our custom
+    implementation of \l {QPaintEngine::}{updateState()}, and
+    enables clipping to the given region. An empty region means that
+    clipping is disabled.
+
+    Our custom update function also makes use of the \c updateClip()
+    helper function that checks if the clip is "simple", i.e., that it
+    can be represented by only one rectangle, and updates the clip
+    region in \l {http://www.svgalib.org}{SVGAlib}.
+
+    \snippet examples/qws/svgalib/svgalibpaintengine.cpp 5
+
+    Finally, we accelerated that drawing of non-rotated, aliased and
+    opaque rectangles in our reimplementation of the \l
+    {QRasterPaintEngine::}{drawRects()} function. The
+    QRasterPaintEngine fallback is used whenever the rectangle is not
+    simple enough.
+
+    \section1 Step 3: Making the Widgets Aware of the Custom Paint Engine
+
+    To activate the custom paint engine, we also need to implement a
+    corresponding paint device and window surface and make some minor
+    adjustments of the graphics driver.
+
+    \list
+        \o \l {Implementing a Custom Paint Device}
+        \o \l {Implementing a Custom Window Surface}
+        \o \l {Adjusting the Graphics Driver}
+    \endlist
+
+    \section2 Implementing a Custom Paint Device
+
+    The custom paint device can be derived from the
+    QCustomRasterPaintDevice class. Reimplement its \l
+    {QCustomRasterPaintDevice::}{paintEngine()} and \l
+    {QCustomRasterPaintDevice::}{memory()} functions to activate the
+    accelerated paint engine:
+
+    \snippet examples/qws/svgalib/svgalibpaintdevice.h 0
+
+    The \l {QCustomRasterPaintDevice::}{paintEngine()} function should
+    return an instance of the \c SvgalibPaintEngine class. The \l
+    {QCustomRasterPaintDevice::}{memory()} function should return a
+    pointer to the buffer which should be used when drawing the
+    widget.
+
+    Our example driver is rendering directly to the screen without any
+    buffering, i.e., our custom pain device's \l
+    {QCustomRasterPaintDevice::}{memory()} function returns a pointer
+    to the framebuffer. For this reason, we must also reimplement the
+    \l {QPaintDevice::}{metric()} function to reflect the metrics of
+    framebuffer.
+
+    \section2 Implementing a Custom Window Surface
+
+    The custom window surface can be derived from the QWSWindowSurface
+    class. QWSWindowSurface manages the memory used when drawing a
+    window.
+
+    \snippet examples/qws/svgalib/svgalibsurface.h 0
+
+    We can implement most of the pure virtual functions inherited from
+    QWSWindowSurface as trivial inline functions, except the 
+    \l {QWindowSurface::}{scroll()} function that actually makes use
+    of some hardware acceleration:
+
+    \snippet examples/qws/svgalib/svgalibsurface.cpp 0
+
+    \section2 Adjusting the Graphics Driver
+
+    Finally, we enable the graphics driver to recognize an instance of
+    our custom window surface:
+
+    \snippet examples/qws/svgalib/svgalibscreen.cpp 7
+    \codeline
+    \snippet examples/qws/svgalib/svgalibscreen.cpp 8
+
+    The \l {QScreen::}{createSurface()} functions are factory
+    functions that determines what kind of surface a top-level window
+    is using. In our example we only use the custom surface if the
+    given window has the Qt::WA_PaintOnScreen attribute or the
+    QT_ONSCREEN_PAINT environment variable is set.
+*/
+