Home · Examples 


Mandelbrot Example

Code:

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 XaoS that provide real-time zooming in the Mandelbrot set, the standard Mandelbrot algorithm is just slow enough for our purposes.


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 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.







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.






The application consists of two classes:

RenderThread Class Implementation

We'll start with the implementation of the RenderThread class:
    private class RenderThread extends Thread {
        private double centerX;
        private double centerY;
        private double scaleFactor;
        private QSize resultSize;
        private boolean restart;

        final int ColormapSize = 512;
        int[] colormap = new int[ColormapSize];

        RenderThread() {

            restart = false;

            for (int i = 0; i < ColormapSize; ++i) {
                double wave = 380.0 + (i * 400.0 / ColormapSize);
                colormap[i] = rgbFromWaveLength(wave);
            }
        }
The class inherits Thread so that it gains the ability to run in a separate thread.

In the constructor, we initialize the restart and abort variables to false. These variables control the flow of the run() method. We also initialize the colormap array, which contains a series of RGB colors.

        synchronized void render(double centerX, double centerY,
                                 double scaleFactor, QSize resultSize) {

            this.centerX = centerX;
            this.centerY = centerY;
            this.scaleFactor = scaleFactor;
            this.resultSize = resultSize;

            if (!isAlive()) {
                start();
            } else {
                restart = true;
                notify();
            }
        }
The render() method is called by the Mandelbrot whenever it needs to generate a new image of the Mandelbrot set. The centerX, centerY, and scaleFactor parameters specify the portion of the fractal to render; resultSize specifies the size of the resulting
QImage.

The method stores the parameters in member variables. If the thread isn't already running, it starts it; otherwise, it sets restart to true (telling run() to stop any unfinished computation and start again with the new parameters) and wakes up the thread, which might be sleeping.

        public void run() {
            QSize resultSize;
            double scaleFactor;
            double centerX;
            double centerY;

            while (true) {

                synchronized (this) {

                    resultSize = this.resultSize;
                    scaleFactor = this.scaleFactor;
                    centerX = this.centerX;
                    centerY = this.centerY;
                }
run() is quite a big method, so we'll break it down into parts.

The method 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 synchronized keyword. Storing the member variables in local variables allows us to minimize the amount of code that needs to be protected. This ensures that the main thread will never have to block for too long when it needs to access RenderThread's member variables (e.g., in render()).

                int halfWidth = resultSize.width() / 2;

                int halfHeight = resultSize.height() / 2;
                QImage.Format format = QImage.Format.Format_RGB32;

                QImage image = new QImage(resultSize, format);

                final int NumPasses = 8;
                int pass = 0;
                while (pass < NumPasses) {
                    final int MaxIterations = (1 << (2 * pass + 6)) + 32;
                    final int Limit = 4;
                    boolean allBlack = true;

                    for (int y = -halfHeight; y < halfHeight; ++y) {
                        if (restart)
                            break;
                        if (abort)
                            return;

                        double ay = centerY + (y * scaleFactor);

                        for (int x = -halfWidth; x < halfWidth; ++x) {
                            double ax = centerX + (x * scaleFactor);
                            double a1 = ax;
                            double b1 = ay;
                            int numIterations = 0;

                            do {
                                ++numIterations;
                                double a2 = (a1 * a1) - (b1 * b1) + ax;
                                double b2 = (2 * a1 * b1) + ay;
                                if ((a2 * a2) + (b2 * b2) > Limit)
                                    break;

                                ++numIterations;
                                a1 = (a2 * a2) - (b2 * b2) + ax;
                                b1 = (2 * a2 * b2) + ay;
                                if ((a1 * a1) + (b1 * b1) > Limit)
                                    break;
                            } while (numIterations < MaxIterations);

                            if (numIterations < MaxIterations) {
                                int index = numIterations % ColormapSize;
                                image.setPixel(x + halfWidth, y + halfHeight,
                                               colormap[index]);

                                allBlack = false;
                            } else {
                                image.setPixel(x + halfWidth, y + halfHeight,
                                               0xff000000);
                            }
                        }
                    }
                    if (allBlack && pass == 0) {
                        pass = 4;
                    } else {
                        synchronized (this) {
                        if (!restart) {
                            //renderedImage.emit(image, scaleFactor);
                            updatePixmap(image, scaleFactor);
                        }
                        }
                        ++pass;
                    }
                }
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 restart has been set to true (by render()), we break out of the loop immediately, so that the control quickly returns to the very top of the outer loop and we fetch the new rendering parameters. Similarly, if we discover that abort has been set to true (by the Mandelbrot.closeEvent() method), we return from the method immediately, terminating the thread.

The core algorithm is beyond the scope of this tutorial.

                synchronized (this) {

                    if (!restart)
                        try {
                            wait();
                        } catch (InterruptedException event) {
                            event.printStackTrace();
                        }
                    restart = false;
                }
            }
        }
Once we're done with all the iterations, we call wait() to put the thread to sleep by calling, unless restart is true. There's no use in keeping a worker thread looping indefinitely while there's nothing to do.
        int rgbFromWaveLength(double wave) {
            double red= 0.0;
            double green = 0.0;
            double blue = 0.0;

            if (wave >= 380.0 && wave <= 440.0) {
                red = -1.0 * (wave - 440.0) / (440.0 - 380.0);
                blue = 1.0;
            } else if (wave >= 440.0 && wave <= 490.0) {
                green = (wave - 440.0) / (490.0 - 440.0);
                blue = 1.0;
            } else if (wave >= 490.0 && wave <= 510.0) {
                green = 1.0;
                blue = -1.0 * (wave - 510.0) / (510.0 - 490.0);
            } else if (wave >= 510.0 && wave <= 580.0) {
                red = (wave - 510.0) / (580.0 - 510.0);
                green = 1.0;
            } else if (wave >= 580.0 && wave <= 645.0) {
                red = 1.0;
                green = -1.0 * (wave - 645.0) / (645.0 - 580.0);
            } else if (wave >= 645.0 && wave <= 780.0) {
                red= 1.0;
            }

            double s = 1.0;
            if (wave > 700.0)
                s = 0.3 + 0.7 * (780.0 - wave) / (780.0 - 700.0);
            else if (wave < 420.0)
                s = 0.3 + 0.7 * (wave - 380.0) / (420.0 - 380.0);

            red = Math.pow(red * s, 0.8) * 255;
            green = Math.pow(green * s, 0.8) * 255;
            blue = Math.pow(blue * s, 0.8) * 255;

            QColor color = new QColor((int) red, (int) green, (int) blue);

            return color.rgb();
        }
    }
The rgbFromWaveLength() method is a helper method that converts a wave length to a RGB value compatible with 32-bit QImages. It is called from the constructor to initialize the colormap array with pleasing colors.

Mandelbrot Class Implementation

The Mandelbrot class uses RenderThread to draw the Mandelbrot set on screen.
public class Mandelbrot extends QWidget {

    private RenderThread thread = new RenderThread();
    private QImage pixmap = new QImage();
    private QPoint pixmapOffset = new QPoint();
    private QPoint lastDragPosition = new QPoint();
    private double centerX;
    private double centerY;
    private double pixmapScale;
    private double currentScale;

    private boolean abort = false;

    final double DefaultCenterX = -0.637011f;
    final double DefaultCenterY = -0.0395159f;
    final double DefaultScale = 0.00403897f;

    final double ZoomInFactor = 0.8f;
    final double ZoomOutFactor = 1 / ZoomInFactor;
    final int ScrollStep = 20;

    private Signal2<QImage, Double> renderedImage =
            new Signal2<QImage, Double>();
The implementation starts with a few constants that we'll need later on. We also declare a signal: Whenever a thread is done rendering an image, it emits the renderedImage() signal.
    public Mandelbrot() {
        this(null);
    }
The interesting part of the constructor is QObject.connect() call. Although it looks like a standard signal-slot connection between two
QObjects, because the signal is emitted in a different thread than the receiver lives in, the connection is effectively a queued connection. These connections are asynchronous (i.e., non-blocking), meaning that the slot will be called at some point after the 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.
    public void paintEvent(QPaintEvent event) {
        QPainter painter = new QPainter();
        painter.begin(this);
        painter.setRenderHint(RenderHint.SmoothPixmapTransform);
        painter.fillRect(rect(), new QBrush(QColor.black));

        if (pixmap.isNull()) {
            String message = tr("Rendering initial image, please wait...");
            painter.setPen(QColor.white);
            painter.drawText(rect(), Qt.AlignmentFlag.AlignCenter.value(),
                             message);
            painter.end();

            return;
        }
In paintEvent(), we start by filling the background with black. If we have nothing yet to paint (pixmap is null), we print a message on the widget asking the user to be patient, returning from the method immediately.
        if (currentScale == pixmapScale) {
            painter.drawImage(pixmapOffset, pixmap);
        } else {
            double scaleFactor = pixmapScale / currentScale;
            int newWidth = (int) (pixmap.width() * scaleFactor);
            int newHeight = (int) (pixmap.height() * scaleFactor);

            int newX = pixmapOffset.x() + (pixmap.width() - newWidth) / 2;
            int newY = pixmapOffset.y() + (pixmap.height() - newHeight) / 2;

            painter.save();
            painter.translate(newX, newY);
            painter.scale(scaleFactor, scaleFactor);

            QMatrix invertedMatrix = painter.worldMatrix().inverted();
            QRect exposed = invertedMatrix.mapRect(rect());
            exposed = exposed.adjusted(-1, -1, 1, 1);

            if(scaleFactor>=0)
                painter.drawImage(pixmapOffset, pixmap);
            else
                painter.drawImage(exposed, pixmap, exposed);

            painter.restore();

        }
If the pixmap has the right scale factor, we draw the pixmap directly onto the widget. Otherwise, we scale and translate the 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.
        String text = tr("Use mouse wheel to zoom.")
                      + tr("Press and hold left mouse button to scroll.");
        QFontMetrics metrics = painter.fontMetrics();
        int textWidth = metrics.width(text);
        int offset = (width() - textWidth) / 2;

        painter.setPen(QPen.NoPen);
        painter.setBrush(new QColor(0, 0, 0, 127));
        painter.drawRect(offset - 5, 0, textWidth + 10, metrics.lineSpacing() + 5);
        painter.setPen(QColor.white);
        painter.drawText(offset, metrics.leading() + metrics.ascent(), text);
        painter.end();
    }
At the end of the paint event handler, we draw a text string and a semi-transparent rectangle on top of the fractal.
    public void resizeEvent(QResizeEvent event) {
        thread.render(centerX, centerY, currentScale, size());
    }
Whenever the user resizes the widget, we call render() to start generating a new image, with the same centerX, centerY, and currentScale parameters but with the new widget size.

Notice that we rely on resizeEvent() being automatically called by Qt when the widget is shown the first time to generate the image the very first time.

    protected void closeEvent(QCloseEvent event) {
        synchronized (thread) {
            abort = true;
            thread.notify();
        }
        super.closeEvent(event);
    }
The closeEvent() method is reimplemented to receive the widget's close events because we want to ensure that the run() method stops running as soon as possible. This is done by setting abort to true, before passing the event to the base class event handler.
    public void keyPressEvent(QKeyEvent event) {
        Qt.Key key = Qt.Key.resolve(event.key());
        switch (key) {
        case Key_Plus:
            zoom(ZoomInFactor);
            break;
        case Key_Minus:
            zoom(ZoomOutFactor);
            break;
        case Key_Left:
            scroll(-ScrollStep, 0);
            break;
        case Key_Right:
            scroll(+ScrollStep, 0);
            break;
        case Key_Down:
            scroll(0, -ScrollStep);
            break;
        case Key_Up:
            scroll(0, +ScrollStep);
            break;
        default:
            super.keyPressEvent(event);
        }
    }
The key press event handler provides a few keyboard bindings for the benefit of users who don't have a mouse. The zoom() and scroll() methods will be covered later.
    public void wheelEvent(QWheelEvent event) {
        int numDegrees = event.delta() / 8;
        double numSteps = numDegrees / 15.0f;
        zoom(Math.pow(ZoomInFactor, numSteps));
    }
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 ZoomInFactor to the second power, i.e. 0.8 * 0.8 = 0.64.
    public void mousePressEvent(QMouseEvent event) {
        if (event.button() == Qt.MouseButton.LeftButton)
            lastDragPosition = event.pos();
    }
When the user presses the left mouse button, we store the mouse pointer position in lastDragPos.
    public void mouseMoveEvent(QMouseEvent event) {
        if (event.buttons().isSet(Qt.MouseButton.LeftButton)) {
            pixmapOffset.add(event.pos());
            pixmapOffset.subtract(lastDragPosition);

            lastDragPosition = event.pos();
            update();
        }
    }
When the user moves the mouse pointer while the left mouse button is pressed, we adjust pixmapOffset to paint the pixmap at a shifted position and call QWidget.update() to force a repaint.
    public void mouseReleaseEvent(QMouseEvent event) {
        if (event.button() == Qt.MouseButton.LeftButton) {
            pixmapOffset.add(event.pos());
            pixmapOffset.subtract(lastDragPosition);
            lastDragPosition = new QPoint();

            int deltaX = (width() - pixmap.width()) / 2 - pixmapOffset.x();
            int deltaY = (height() - pixmap.height()) / 2 - pixmapOffset.y();
            scrollImage(deltaX, deltaY);
        }
    }
When the left mouse button is released, we update pixmapOffset just like we did on a mouse move and we reset lastDragPosition to a default value. Then, we call scroll() to render a new image for the new position. (Adjusting pixmapOffset isn't sufficient because areas revealed when dragging the pixmap are drawn in black.)
    private void updatePixmap(QImage image, Double scaleFactor) {
        if (!lastDragPosition.isNull())
            return;
        pixmap = image;
        pixmapOffset = new QPoint();
        lastDragPosition = new QPoint();
        pixmapScale = scaleFactor;

        QApplication.invokeLater(new Runnable() {
            public void run() {
                synchronized (thread) {
                    if(!abort)
                        update();
                }
            }
        });
    }
The 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 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 paintEvent().

    protected void zoom(double zoomFactor) {
        currentScale *= zoomFactor;
        update();
        thread.render(centerX, centerY, currentScale, size());
    }
In zoom(), we recompute currentScale. 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 currentScale value.
    public void scrollImage(int deltaX, int deltaY) {
        centerX += deltaX * currentScale;
        centerY += deltaY * currentScale;
        update();
        thread.render(centerX, centerY, currentScale, size());
    }
scroll() is similar to zoom(), except that the affected parameters are centerX and centerY.

The main() Method

The application's multithreaded nature has no impact on its main() method, which is as simple as usual:
    public static void main(String args[]) {
        QApplication.initialize(args);
        Mandelbrot mainWindow = new Mandelbrot();
        mainWindow.show();
        QApplication.exec();
    }

}


Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies) Trademarks
Qt Jambi 4.5.2_01