Mandelbrot Example

MandelbrotWidget Class Implementation

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

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

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

 MandelbrotWidget::MandelbrotWidget(QWidget *parent)
     : QWidget(parent)
 {
     centerX = DefaultCenterX;
     centerY = DefaultCenterY;
     pixmapScale = DefaultScale;
     curScale = DefaultScale;

     qRegisterMetaType<QImage>("QImage");
     connect(&thread, SIGNAL(renderedImage(const QImage &, double)),
             this, SLOT(updatePixmap(const QImage &, double)));

     setWindowTitle(tr("Mandelbrot"));
     setCursor(Qt::CrossCursor);
     resize(550, 400);
 }

The interesting part of the constructor is the qRegisterMetaType() and QObject::connect() calls. Let's start with the 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.

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.

 void MandelbrotWidget::paintEvent(QPaintEvent * /* event */)
 {
     QPainter painter(this);
     painter.fillRect(rect(), Qt::black);

     if (pixmap.isNull()) {
         painter.setPen(Qt::white);
         painter.drawText(rect(), Qt::AlignCenter,
                          tr("Rendering initial image, please wait..."));
         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 and return from the function immediately.

     if (curScale == pixmapScale) {
         painter.drawPixmap(pixmapOffset, pixmap);
     } else {
         double scaleFactor = pixmapScale / curScale;
         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);
         QRectF exposed = painter.matrix().inverted().mapRect(rect()).adjusted(-1, -1, 1, 1);
         painter.drawPixmap(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.

     QString text = tr("Use mouse wheel or the '+' and '-' keys to zoom. "
                       "Press and hold left mouse button to scroll.");
     QFontMetrics metrics = painter.fontMetrics();
     int textWidth = metrics.width(text);

     painter.setPen(Qt::NoPen);
     painter.setBrush(QColor(0, 0, 0, 127));
     painter.drawRect((width() - textWidth) / 2 - 5, 0, textWidth + 10,
                      metrics.lineSpacing() + 5);
     painter.setPen(Qt::white);
     painter.drawText((width() - textWidth) / 2,
                      metrics.leading() + metrics.ascent(), text);
 }

At the end of the paint event handler, we draw a text string and a semi-transparent rectangle on top of the fractal.

 void MandelbrotWidget::resizeEvent(QResizeEvent * /* event */)
 {
     thread.render(centerX, centerY, curScale, size());
 }

Whenever the user resizes the widget, we call render() to start generating a new image, with the same centerX, centerY, and curScale 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.

 void MandelbrotWidget::keyPressEvent(QKeyEvent *event)
 {
     switch (event->key()) {
     case Qt::Key_Plus:
         zoom(ZoomInFactor);
         break;
     case Qt::Key_Minus:
         zoom(ZoomOutFactor);
         break;
     case Qt::Key_Left:
         scroll(-ScrollStep, 0);
         break;
     case Qt::Key_Right:
         scroll(+ScrollStep, 0);
         break;
     case Qt::Key_Down:
         scroll(0, -ScrollStep);
         break;
     case Qt::Key_Up:
         scroll(0, +ScrollStep);
         break;
     default:
         QWidget::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() functions will be covered later.

 void MandelbrotWidget::wheelEvent(QWheelEvent *event)
 {
     int numDegrees = event->delta() / 8;
     double numSteps = numDegrees / 15.0f;
     zoom(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.

 void MandelbrotWidget::mousePressEvent(QMouseEvent *event)
 {
     if (event->button() == Qt::LeftButton)
         lastDragPos = event->pos();
 }

When the user presses the left mouse button, we store the mouse pointer position in lastDragPos.

 void MandelbrotWidget::mouseMoveEvent(QMouseEvent *event)
 {
     if (event->buttons() & Qt::LeftButton) {
         pixmapOffset += event->pos() - lastDragPos;
         lastDragPos = 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.

 void MandelbrotWidget::mouseReleaseEvent(QMouseEvent *event)
 {
     if (event->button() == Qt::LeftButton) {
         pixmapOffset += event->pos() - lastDragPos;
         lastDragPos = QPoint();

         int deltaX = (width() - pixmap.width()) / 2 - pixmapOffset.x();
         int deltaY = (height() - pixmap.height()) / 2 - pixmapOffset.y();
         scroll(deltaX, deltaY);
     }
 }

When the left mouse button is released, we update pixmapOffset just like we did on a mouse move and we reset lastDragPos 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.)

 void MandelbrotWidget::updatePixmap(const QImage &image, double scaleFactor)
 {
     if (!lastDragPos.isNull())
         return;

     pixmap = QPixmap::fromImage(image);
     pixmapOffset = QPoint();
     lastDragPos = QPoint();
     pixmapScale = scaleFactor;
     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().

 void MandelbrotWidget::zoom(double zoomFactor)
 {
     curScale *= zoomFactor;
     update();
     thread.render(centerX, centerY, curScale, size());
 }

In zoom(), we recompute 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 curScale value.

 void MandelbrotWidget::scroll(int deltaX, int deltaY)
 {
     centerX += deltaX * curScale;
     centerY += deltaY * curScale;
     update();
     thread.render(centerX, centerY, curScale, size());
 }

scroll() is similar to zoom(), except that the affected parameters are centerX and centerY.

 int main(int argc, char *argv[])
 {
     QApplication app(argc, argv);
     MandelbrotWidget widget;
     widget.show();
     return app.exec();
 }