/****************************************************************************
**
** 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$
** 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 qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page qt-embedded-accel.html

    \target add your graphics driver to Qt for Embedded Linux

    \title Adding an Accelerated Graphics Driver to Qt for Embedded Linux
    \ingroup qt-embedded-linux

    In \l{Qt for Embedded Linux}, painting is a pure software implementation
    normally performed in two steps. First, each window is rendered
    onto a QWSWindowSurface using QPaintEngine. Second, the server
    composes the surface images and copies the composition to the
    screen (see \l{Qt for Embedded Linux Architecture} for details).
    \l{Qt for Embedded Linux} uses QRasterPaintEngine (a raster-based implementation of
    QPaintEngine) to implement painting operations, and uses QScreen
    to implement window composition.

    It is possible to add an accelerated graphics driver to take
    advantage of available hardware resources. This is described in
    detail in the \l {Accelerated Graphics Driver Example} which uses
    the following approach:

    \tableofcontents

    \warning This feature is under development and is subject to
    change.

    \section1 Step 1: Create a Custom Screen

    Create a custom screen by deriving from the QScreen class.

    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. These functions are used to configure the
    hardware, or query its configuration. The \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.

    You might want to accelerate the final copying to the screen by
    reimplementing the \l {QScreen::}{blit()} and \l
    {QScreen::}{solidFill()} functions.

    \section1 Step 2: Implement a Custom Raster Paint Engine

    Implement the painting operations by subclassing the
    QRasterPaintEngine class.

    To accelerate a graphics primitive, simply reimplement the
    corresponding function in your custom paint engine. If there is
    functionality you do not want to reimplement (such as certain
    pens, brushes, modes, etc.), you can just call the corresponding
    base class implementation.

    \section1 Step 3: Make the Paint Device Aware of Your Paint Engine

    To activate your paint engine you must create a subclass of the
    QCustomRasterPaintDevice class and reimplement its \l
    {QCustomRasterPaintDevice::}{paintEngine()} function. Let this
    function return a pointer to your paint engine. In addition, the
    QCustomRasterPaintDevice::memory() function must be reimplemented
    to return a pointer to the buffer where the painting should be
    done.

    \table
    \header \o Acceleration Without a Memory Buffer
    \row
    \o

    By default the QRasterPaintEngine draws into a memory buffer (this can
    be local memory, shared memory or graphics memory mapped into
    application memory).
    In some cases you might want to avoid using a memory buffer directly,
    e.g if you want to use an accelerated graphic controller to handle all
    the buffer manipulation. This can be implemented by  reimplementing
    the QCustomRasterPaintDevice::memory() function to return 0 (meaning
    no buffer available). Then, whenever a color or image buffer normally
    would be written into paint engine buffer, the paint engine will call the
    QRasterPaintEngine::drawColorSpans() and
    QRasterPaintEngine::drawBufferSpan() functions instead.

    Note that the default implementations of these functions only
    calls qFatal() with an error message; reimplement the functions
    and let them do the appropriate communication with the accelerated
    graphics controller.

    \endtable

    \section1 Step 4: Make the Window Surface Aware of Your Paint Device

    Derive from the QWSWindowSurface class and reimplement its \l
    {QWSWindowSurface::}{paintDevice()} function. Make this function
    return a pointer to your custom raster paint device.

    \section1 Step 5: Enable Creation of an Instance of Your Window Surface

    Finally, reimplement QScreen's \l {QScreen::}{createSurface()}
    function and make this function able to create an instance of your
    QWSWindowSurface subclass.
*/