Development/Tutorials/Graphics/Performance

QPixmap vs. QImage

QPixmap and QImage both contain images, but there is a key difference between the two that's important to understand when writing graphics code.

QImage

When you're using a QImage, the image data is stored your application's memory in a format of your choosing. This has the advantage that you can easily get to and manipulate the pixel data directly.

The disadvantages are that QPainter can't take advantage of the graphics hardware when rendering to a QImage. In other words, all rendering to a QImage is done without hardware acceleration.

QPixmap

When you're using a QPixmap, the image data is not stored in your application's memory, but in the X server process, and possibly in video RAM. The data stored in the QPixmap object itself is just a serial number that refers to the image in the X server (the pixmap).

The disadvantage of using a QPixmap is that you can't get to the pixel data directly, since it's out of process. QPainter can only manipulate a QPixmap indirectly, by sending requests to the X server asking it to manipulate the pixmap.

The advantage is that the X server can use the graphics hardware to do this, which means that when drawing on a QPixmap, you get hardware acceleration.

Conversions are expensive

Converting a QImage to a QPixmap is an expensive operation because the image data must first be converted to the appropriate format for pixmaps, and then be marshalled and sent over the socket to the X server.

Converting a QPixmap to a QImage is an even more expensive operation, because in order to do so your application must first send a request to the X server asking it to send the pixmap data to your application. It must then block and wait, first for the X server process to be scheduled in by the kernel, then while the X server marshalls and sends the pixmap data over the socket. When your application has received the data, it must then convert it to an appropriate QImage format.

Converting a QImage to a QPixmap is a less expensive operation because it's a fire-and-forget operation. Your application doesn't have to wait for the X server to receive the image data after the data has been written to the socket. It can simply continue executing.

Keep in mind that a QImage can't be drawn on a QPixmap or a QWidget without first being converted to a QPixmap. QPainter does this implicitly when you call QPainter::drawImage() on a QPixmap or a QWidget. Likewise, a QPixmap can't be drawn on a QImage without first being converted to a QImage.

QPainter::setOpacity()

Never call QPainter::setOpacity() when painting on a QPixmap or a QWidget. QPainter::setOpacity() effectively disables all hardware acceleration, causing all subsequent rendering operations to be done in software. This means that a call to QPainter::setOpacity() in a performance critical path is the kiss of death.

An alternative approach to the problem

If you're drawing something with a solid color, such as a QPainterPath, a line, a rectangle etc., the easiest and also the fastest solution is to just change the alpha value of the color you're using, like this:

QColor c = color; c.setAlphaF(c.alphaF() * opacity);

If you're using pixmaps, gradients or brushes that you can't easily change the opacity of, you should use the following method instead.

Create a temporary pixmap, initialize it to fully transparent, and then draw on it with normal opacity. When you're done drawing on it, use the DestinationIn composition mode to reduce the alpha of the pixmap, and then draw the pixmap itself where you want the semi-transparent contents. If you need the same content again (for example when you're doing a fade out or fade in animation), it might pay off to cache the fully opaque version.

QPixmap pixmap(size); pixmap.fill(Qt::transparent);

QPainter p; p.begin(&pixmap);

// Do the rendering with full opacity

p.setCompositionMode(QPainter::CompositionMode_DestinationIn); p.fillRect(pixmap.rect(), QColor(0, 0, 0, opacity)); p.end();

painter->drawPixmap(0, 0, pixmap);

Note that you can check if setOpacity() is fast by calling painter->paintEngine()->hasFeature(QPaintEngine::ConstantOpacity), but my recommendation is to avoid it completely since it won't be fast on our main platform with the current Qt version (4.4 beta).

QPixmap::setAlphaChannel()

Never use QPixmap::setAlphaChannel() to make a pixmap semi-transparent. In fact you should never ever call QPixmap::setAlphaChannel() for any reason if you can avoid it. This function will convert both pixmaps to images (this involves two blocking synchronous calls to the X server, plus expensive image transport over the socket for each call), expensive format conversion of both images, copying the alpha channel one pixel at a time from the alpha image to the other image, followed by a final conversion of the resulting image back to a pixmap (which is also a very expensive operation).

The right way to do it

Check if the pixmap has an alpha channel, using QPixmap::hasAlphaChannel(). If it has one, start a QPainter on the pixmap, and reduce the alpha using the DestinationIn composition mode. If the pixmap doesn't have an alpha channel, you're going to have to create a new pixmap that has one and copy the content of the original pixmap into it, like this:

QPixmap temp(pixmap.size()); temp.fill(Qt::transparent);

QPainter p(&temp); p.setCompositionMode(QPainter::CompositionMode_Source); p.drawPixmap(0, 0, pixmap); p.setCompositionMode(QPainter::CompositionMode_DestinationIn); p.fillRect(temp.rect(), QColor(0, 0, 0, opacity)); p.end();

pixmap = temp;