[Development] High-dpi Qt best practices

[Sorvig Morten]

While preparing an upcoming blog entry I've collected some best practices regarding raster graphics (QImage and QPixmap). These apply to internal Qt development as well. The patch is still pending so they are open for discussion.

(I use image and pixmap interchangeably here, most points apply to both)

* Start by providing high-resolution artwork. You can provide 2x versions only and let Qt scale them down, or for best performance and image quality provide pre-scaled or hand-made 1x and 2x versions.

* Set the QT_HIDPI_AWARE environment variable. (Changes the behaviour of QIcon::pixmap)

• Use QIcon to manage the artwork versions. Use QIcon::pixmap(QWindow, QSize) to get an appropriate pixmap for a given window and point size. If you don’t know which window you are targeting you can use QIcon::pixmap(QSize), which will work correctly on single-display systems and and use the “best” display on  multiple-display systems.

• Alternatively, manage the versions yourself. Set a dpi scale factor of 2 on the high-dpi version, either by appending "@2x" to the file name or by calling QImage::setDpiScaleFactor(2) yourself. Use QWindow::dpiScaleFactor() or qApp->dpiScaleFactor() to get the target scale factor.

* Don’t scale pixmaps to specific pixel sizes unless you know what you are doing.

* Don’t use pixmap sizes directly in layout calculations. Divide by the pixmap scale factor: 
   QSize pointSze = pixmap.size() / pixmap.dpiScaleFactor();

* QPainter::drawPixmap(QPoint, ...) works correctly with high-dpi pixmaps if the dpi scale factor is set, that is pixmaps from QIcon::pixmap(), pixmaps loaded from “@2x” files, or pixmaps where you call setDpiScaleFactor().

* QPainter::drawPixmap(QRect, ...) works correctly for all pixmaps and will draw high-dpi content if the source pixmap provides enough pixels. If you calculate the rect from the pixmap remember to use dpiScaleFactor() as above.

* 2x pixmaps on a 2x high-dpi display is an optimized case in the raster paint engine, similar to 1x pixmaps on “standard” displays.

* Most Qt API is in points (even QStyle::PixelMetric). The main exception is image and pixmap geometry, which is in pixels.

Next on my agenda is high-dpi OpenGL, scene graph and Qt Quick.

- Morten