/****************************************************************************

**

** Copyright (C) 2010 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$

**

****************************************************************************/

/*!

    \example threads/mandelbrot

    \title Mandelbrot Example

    The Mandelbrot example shows how to use a worker thread to

    perform heavy computations without blocking the main thread's

    event loop.

    The heavy computation here is the Mandelbrot set, probably the

    world's most famous fractal. These days, while sophisticated

    programs such as \l{XaoS} that provide real-time zooming in the

    Mandelbrot set, the standard Mandelbrot algorithm is just slow

    enough for our purposes.

    \image mandelbrot-example.png Screenshot of the Mandelbrot example

    In real life, the approach described here is applicable to a

    large set of problems, including synchronous network I/O and

    database access, where the user interface must remain responsive

    while some heavy operation is taking place. The \l

    network/blockingfortuneclient example shows the same principle at

    work in a TCP client.

    The Mandelbrot application supports zooming and scrolling using

    the mouse or the keyboard. To avoid freezing the main thread's

    event loop (and, as a consequence, the application's user

    interface), we put all the fractal computation in a separate

    worker thread. The thread emits a signal when it is done

    rendering the fractal.

    During the time where the worker thread is recomputing the

    fractal to reflect the new zoom factor position, the main thread

    simply scales the previously rendered pixmap to provide immediate

    feedback. The result doesn't look as good as what the worker

    thread eventually ends up providing, but at least it makes the

    application more responsive. The sequence of screenshots below

    shows the original image, the scaled image, and the rerendered

    image.

    \table

    \row

    \o \inlineimage mandelbrot_zoom1.png

    \o \inlineimage mandelbrot_zoom2.png

    \o \inlineimage mandelbrot_zoom3.png

    \endtable

    Similarly, when the user scrolls, the previous pixmap is scrolled

    immediately, revealing unpainted areas beyond the edge of the

    pixmap, while the image is rendered by the worker thread.

    \table

    \row

    \o \inlineimage mandelbrot_scroll1.png

    \o \inlineimage mandelbrot_scroll2.png

    \o \inlineimage mandelbrot_scroll3.png

    \endtable

    The application consists of two classes:

    \list

    \o \c RenderThread is a QThread subclass that renders

       the Mandelbrot set.

    \o \c MandelbrotWidget is a QWidget subclass that shows the

       Mandelbrot set on screen and lets the user zoom and scroll.

    \endlist

    If you are not already familiar with Qt's thread support, we

    recommend that you start by reading the \l{Thread Support in Qt}

    overview.

    \section1 RenderThread Class Definition

    We'll start with the definition of the \c RenderThread class:

    \snippet examples/threads/mandelbrot/renderthread.h 0

    The class inherits QThread so that it gains the ability to run in

    a separate thread. Apart from the constructor and destructor, \c

    render() is the only public function. Whenever the thread is done

    rendering an image, it emits the \c renderedImage() signal.

    The protected \c run() function is reimplemented from QThread. It

    is automatically called when the thread is started.

    In the \c private section, we have a QMutex, a QWaitCondition,

    and a few other data members. The mutex protects the other data

    member.

    \section1 RenderThread Class Implementation

    \snippet examples/threads/mandelbrot/renderthread.cpp 0

    In the constructor, we initialize the \c restart and \c abort

    variables to \c false. These variables control the flow of the \c

    run() function.

    We also initialize the \c colormap array, which contains a series

    of RGB colors.

    \snippet examples/threads/mandelbrot/renderthread.cpp 1

    The destructor can be called at any point while the thread is

    active. We set \c abort to \c true to tell \c run() to stop

    running as soon as possible. We also call

    QWaitCondition::wakeOne() to wake up the thread if it's sleeping.

    (As we will see when we review \c run(), the thread is put to

    sleep when it has nothing to do.)

    The important thing to notice here is that \c run() is executed

    in its own thread (the worker thread), whereas the \c

    RenderThread constructor and destructor (as well as the \c

    render() function) are called by the thread that created the

    worker thread. Therefore, we need a mutex to protect accesses to

    the \c abort and \c condition variables, which might be accessed

    at any time by \c run().

    At the end of the destructor, we call QThread::wait() to wait

    until \c run() has exited before the base class destructor is

    invoked.

    \snippet examples/threads/mandelbrot/renderthread.cpp 2

    The \c render() function is called by the \c MandelbrotWidget

    whenever it needs to generate a new image of the Mandelbrot set.

    The \c centerX, \c centerY, and \c scaleFactor parameters specify

    the portion of the fractal to render; \c resultSize specifies the

    size of the resulting QImage.

    The function stores the parameters in member variables. If the

    thread isn't already running, it starts it; otherwise, it sets \c

    restart to \c true (telling \c run() to stop any unfinished

    computation and start again with the new parameters) and wakes up

    the thread, which might be sleeping.

    \snippet examples/threads/mandelbrot/renderthread.cpp 3

    \c run() is quite a big function, so we'll break it down into

    parts.

    The function body is an infinite loop which starts by storing the

    rendering parameters in local variables. As usual, we protect

    accesses to the member variables using the class's mutex. Storing

    the member variables in local variables allows us to minimize the

    amout of code that needs to be protected by a mutex. This ensures

    that the main thread will never have to block for too long when

    it needs to access \c{RenderThread}'s member variables (e.g., in

    \c render()).

    The \c forever keyword is, like \c foreach, a Qt pseudo-keyword.

    \snippet examples/threads/mandelbrot/renderthread.cpp 4

    \snippet examples/threads/mandelbrot/renderthread.cpp 5

    \snippet examples/threads/mandelbrot/renderthread.cpp 6

    \snippet examples/threads/mandelbrot/renderthread.cpp 7

    Then comes the core of the algorithm. Instead of trying to create

    a perfect Mandelbrot set image, we do multiple passes and

    generate more and more precise (and computationally expensive)

    approximations of the fractal.

    If we discover inside the loop that \c restart has been set to \c

    true (by \c render()), we break out of the loop immediately, so

    that the control quickly returns to the very top of the outer

    loop (the \c forever loop) and we fetch the new rendering

    parameters. Similarly, if we discover that \c abort has been set

    to \c true (by the \c RenderThread destructor), we return from

    the function immediately, terminating the thread.

    The core algorithm is beyond the scope of this tutorial.

    \snippet examples/threads/mandelbrot/renderthread.cpp 8

    \snippet examples/threads/mandelbrot/renderthread.cpp 9

    Once we're done with all the iterations, we call

    QWaitCondition::wait() to put the thread to sleep by calling,

    unless \c restart is \c true. There's no use in keeping a worker

    thread looping indefinitely while there's nothing to do.

    \snippet examples/threads/mandelbrot/renderthread.cpp 10

    The \c rgbFromWaveLength() function is a helper function that

    converts a wave length to a RGB value compatible with 32-bit

    \l{QImage}s. It is called from the constructor to initialize the

    \c colormap array with pleasing colors.

    \section1 MandelbrotWidget Class Defintion

    The \c MandelbrotWidget class uses \c RenderThread to draw the

    Mandelbrot set on screen. Here's the class definition:

    \snippet examples/threads/mandelbrot/mandelbrotwidget.h 0

    The widget reimplements many event handlers from QWidget. In

    addition, it has an \c updatePixmap() slot that we'll connect to

    the worker thread's \c renderedImage() signal to update the

    display whenever we receive new data from the thread.

    Among the private variables, we have \c thread of type \c

    RenderThread and \c pixmap, which contains the last rendered

    image.

    \section1 MandelbrotWidget Class Implementation

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 0

    The implementation starts with a few contants that we'll need

    later on.

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 1

    The interesting part of the constructor is the

    qRegisterMetaType() and QObject::connect() calls. Let's start

    with the \l{QObject::connect()}{connect()} call.

    Although it looks like a standard signal-slot connection between

    two \l{QObject}s, because the signal is emitted in a different

    thread than the receiver lives in, the connection is effectively a

    \l{Qt::QueuedConnection}{queued connection}. These connections are

    asynchronous (i.e., non-blocking), meaning that the slot will be

    called at some point after the \c emit statement. What's more, the

    slot will be invoked in the thread in which the receiver lives.

    Here, the signal is emitted in the worker thread, and the slot is

    executed in the GUI thread when control returns to the event loop.

    With queued connections, Qt must store a copy of the arguments

    that were passed to the signal so that it can pass them to the

    slot later on. Qt knows how to take of copy of many C++ and Qt

    types, but QImage isn't one of them. We must therefore call the

    template function qRegisterMetaType() before we can use QImage

    as parameter in queued connections.

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 2

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 3

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 4

    In \l{QWidget::paintEvent()}{paintEvent()}, we start by filling

    the background with black. If we have nothing yet to paint (\c

    pixmap is null), we print a message on the widget asking the user

    to be patient and return from the function immediately.

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 5

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 6

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 7

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 8

    If the pixmap has the right scale factor, we draw the pixmap directly onto

    the widget. Otherwise, we scale and translate the \l{The Coordinate

    System}{coordinate system} before we draw the pixmap. By reverse mapping

    the widget's rectangle using the scaled painter matrix, we also make sure

    that only the exposed areas of the pixmap are drawn. The calls to

    QPainter::save() and QPainter::restore() make sure that any painting

    performed afterwards uses the standard coordinate system.

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 9

    At the end of the paint event handler, we draw a text string and

    a semi-transparent rectangle on top of the fractal.

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 10

    Whenever the user resizes the widget, we call \c render() to

    start generating a new image, with the same \c centerX, \c

    centerY, and \c curScale parameters but with the new widget size.

    Notice that we rely on \c resizeEvent() being automatically

    called by Qt when the widget is shown the first time to generate

    the image the very first time.

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 11

    The key press event handler provides a few keyboard bindings for

    the benefit of users who don't have a mouse. The \c zoom() and \c

    scroll() functions will be covered later.

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 12

    The wheel event handler is reimplemented to make the mouse wheel

    control the zoom level. QWheelEvent::delta() returns the angle of

    the wheel mouse movement, in eights of a degree. For most mice,

    one wheel step corresponds to 15 degrees. We find out how many

    mouse steps we have and determine the zoom factor in consequence.

    For example, if we have two wheel steps in the positive direction

    (i.e., +30 degrees), the zoom factor becomes \c ZoomInFactor

    to the second power, i.e. 0.8 * 0.8 = 0.64.

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 13

    When the user presses the left mouse button, we store the mouse

    pointer position in \c lastDragPos.

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 14

    When the user moves the mouse pointer while the left mouse button

    is pressed, we adjust \c pixmapOffset to paint the pixmap at a

    shifted position and call QWidget::update() to force a repaint.

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 15

    When the left mouse button is released, we update \c pixmapOffset

    just like we did on a mouse move and we reset \c lastDragPos to a

    default value. Then, we call \c scroll() to render a new image

    for the new position. (Adjusting \c pixmapOffset isn't sufficient

    because areas revealed when dragging the pixmap are drawn in

    black.)

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 16

    The \c updatePixmap() slot is invoked when the worker thread has

    finished rendering an image. We start by checking whether a drag

    is in effect and do nothing in that case. In the normal case, we

    store the image in \c pixmap and reinitialize some of the other

    members. At the end, we call QWidget::update() to refresh the

    display.

    At this point, you might wonder why we use a QImage for the

    parameter and a QPixmap for the data member. Why not stick to one

    type? The reason is that QImage is the only class that supports

    direct pixel manipulation, which we need in the worker thread. On

    the other hand, before an image can be drawn on screen, it must

    be converted into a pixmap. It's better to do the conversion once

    and for all here, rather than in \c paintEvent().

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 17

    In \c zoom(), we recompute \c curScale. Then we call

    QWidget::update() to draw a scaled pixmap, and we ask the worker

    thread to render a new image corresponding to the new \c curScale

    value.

    \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 18

    \c scroll() is similar to \c zoom(), except that the affected

    parameters are \c centerX and \c centerY.

    \section1 The main() Function

    The application's multithreaded nature has no impact on its \c

    main() function, which is as simple as usual:

    \snippet examples/threads/mandelbrot/main.cpp 0

*/