source: trunk/doc/src/examples/svgalib.qdoc@ 677

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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.
**
** 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 have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $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