Document loading of high resolution versions of images.

Task-number: QTBUG-38858
Change-Id: I87ee18b66e137f5f5c01d77910f1a7f256b85e18
Reviewed-by: Alessandro Portale <alessandro.portale@digia.com>

src/gui/image/qicon.cpp

@@ -989,10 +989,16 @@ void QIcon::addPixmap(const QPixmap &pixmap, Mode mode, State state)
     QImageWriter::supportedImageFormats() functions to retrieve a
     complete list of the supported file formats.
 
-    Note: When you add a non-empty filename to a QIcon, the icon becomes
+    If a high resolution version of the image exists (identified by
+    the suffix \c @2x on the base name), it is automatically loaded
+    and added with the \e{device pixel ratio} set to a value of 2.
+    This can be disabled by setting the environment variable
+    \c QT_HIGHDPI_DISABLE_2X_IMAGE_LOADING (see QImageReader).
+
+    \note When you add a non-empty filename to a QIcon, the icon becomes
     non-null, even if the file doesn't exist or points to a corrupt file.
 
-    \sa addPixmap()
+    \sa addPixmap(), QPixmap::devicePixelRatio()
  */
 void QIcon::addFile(const QString &fileName, const QSize &size, Mode mode, State state)
 {

src/gui/image/qimage.cpp

@@ -1391,14 +1391,14 @@ QVector<QRgb> QImage::colorTable() const
 
 /*!
     Returns the device pixel ratio for the image. This is the
-    ratio between image pixels and device-independent pixels.
+    ratio between \e{device pixels} and \e{device independent pixels}.
 
     Use this function when calculating layout geometry based on
     the image size: QSize layoutSize = image.size() / image.devicePixelRatio()
 
     The default value is 1.0.
 
-    \sa setDevicePixelRatio()
+    \sa setDevicePixelRatio(), QImageReader
 */
 qreal QImage::devicePixelRatio() const
 {
@@ -1423,7 +1423,8 @@ qreal QImage::devicePixelRatio() const
     image size will take the ratio into account:
     QSize layoutSize = image.size() / image.devicePixelRatio()
     The net effect of this is that the image is displayed as
-    high-dpi image rather than a large image.
+    high-DPI image rather than a large image
+    (see \l{Drawing High Resolution Versions of Pixmaps and Images}).
 
     \sa devicePixelRatio()
 */

src/gui/image/qimagereader.cpp

@@ -74,6 +74,8 @@
     that occurred, or errorString() to get a human readable
     description of what went wrong.
 
+    \section1 Formats
+
     Call supportedImageFormats() for a list of formats that
     QImageReader can read. QImageReader supports all built-in image
     formats, in addition to any image format plugins that support
@@ -85,7 +87,19 @@
     stream contents. You can enable or disable this feature, by calling
     setAutoDetectImageFormat().
 
+    \section1 High Resolution Versions of Images
+
+    It is possible to provide high resolution versions of images should a scaling
+    between \e{device pixels} and \e{device independent pixels} be in effect.
+
+    The high resolution version is marked by the suffix \c @2x on the base name.
+    The image read will have its \e{device pixel ratio} set to a value of 2.
+
+    This can be disabled by setting the environment variable
+    \c QT_HIGHDPI_DISABLE_2X_IMAGE_LOADING.
+
     \sa QImageWriter, QImageIOHandler, QImageIOPlugin, QMimeDatabase
+    \sa QImage::devicePixelRatio(), QPixmap::devicePixelRatio(), QIcon, QPainter::drawPixmap(), QPainter::drawImage(), Qt::AA_UseHighDpiPixmaps
 */
 
 /*!

src/gui/image/qpixmap.cpp

@@ -648,14 +648,14 @@ void QPixmap::setMask(const QBitmap &mask)
 
 /*!
     Returns the device pixel ratio for the pixmap. This is the
-    ratio between pixmap pixels and device-independent pixels.
+    ratio between \e{device pixels} and \e{device independent pixels}.
 
     Use this function when calculating layout geometry based on
     the pixmap size: QSize layoutSize = image.size() / image.devicePixelRatio()
 
     The default value is 1.0.
 
-    \sa setDevicePixelRatio()
+    \sa setDevicePixelRatio(), QImageReader
 */
 qreal QPixmap::devicePixelRatio() const
 {
@@ -680,7 +680,8 @@ qreal QPixmap::devicePixelRatio() const
     pixmap size will take the ratio into account:
     QSize layoutSize = pixmap.size() / pixmap.devicePixelRatio()
     The net effect of this is that the pixmap is displayed as
-    high-dpi pixmap rather than a large pixmap.
+    high-DPI pixmap rather than a large pixmap
+    (see \l{Drawing High Resolution Versions of Pixmaps and Images}).
 
         \sa devicePixelRatio()
 */

src/gui/painting/qpainter.cpp

@@ -1106,6 +1106,11 @@ void QPainterPrivate::updateState(QPainterState *newState)
     \li \inlineimage qpainter-pathstroking.png
     \endtable
 
+    Text drawing is done using drawText(). When you need
+    fine-grained positioning, boundingRect() tells you where a given
+    drawText() command will draw.
+
+    \section1 Drawing Pixmaps and Images
 
     There are functions to draw pixmaps/images, namely drawPixmap(),
     drawImage() and drawTiledPixmap(). Both drawPixmap() and drawImage()
@@ -1113,15 +1118,25 @@ void QPainterPrivate::updateState(QPainterState *newState)
     on-screen while drawImage() may be faster on a QPrinter or other
     devices.
 
-    Text drawing is done using drawText(). When you need
-    fine-grained positioning, boundingRect() tells you where a given
-    drawText() command will draw.
-
     There is a drawPicture() function that draws the contents of an
     entire QPicture. The drawPicture() function is the only function
     that disregards all the painter's settings as QPicture has its own
     settings.
 
+    \section2 Drawing High Resolution Versions of Pixmaps and Images
+
+    High resolution versions of pixmaps have a \e{device pixel ratio} value larger
+    than 1 (see QImageReader, QPixmap::devicePixelRatio()). Should it match the value
+    of the underlying QPaintDevice, it is drawn directly onto the device with no
+    additional transformation applied.
+
+    This is for example the case when drawing a QPixmap of 64x64 pixels size with
+    a device pixel ratio of 2 onto a high DPI screen which also has
+    a device pixel ratio of 2. Note that the pixmap is then effectively 32x32
+    pixels in \e{user space}. Code paths in Qt that calculate layout geometry
+    based on the pixmap size will use this size. The net effect of this is that
+    the pixmap is displayed as high DPI pixmap rather than a large pixmap.
+
     \section1 Rendering Quality
 
     To get the optimal rendering result using QPainter, you should use
@@ -5024,6 +5039,8 @@ static inline QPointF roundInDeviceCoordinates(const QPointF &p, const QTransfor
     into the given \a target in the paint device.
 
     \note The pixmap is scaled to fit the rectangle, if both the pixmap and rectangle size disagree.
+    \note See \l{Drawing High Resolution Versions of Pixmaps and Images} on how this is affected
+    by QPixmap::devicePixelRatio().
 
     \table 100%
     \row
@@ -5038,7 +5055,7 @@ static inline QPointF roundInDeviceCoordinates(const QPointF &p, const QTransfor
     transparent. Drawing bitmaps with gradient or texture colors is
     not supported.
 
-    \sa drawImage()
+    \sa drawImage(), QPixmap::devicePixelRatio()
 */
 void QPainter::drawPixmap(const QPointF &p, const QPixmap &pm)
 {
@@ -7694,6 +7711,8 @@ void QPainterState::init(QPainter *p) {
     into the \a target rectangle in the paint device.
 
     \note The image is scaled to fit the rectangle, if both the image and rectangle size disagree.
+    \note See \l{Drawing High Resolution Versions of Pixmaps and Images} on how this is affected
+    by QImage::devicePixelRatio().
 
     If the image needs to be modified to fit in a lower-resolution
     result (e.g. converting from 32-bit to 8-bit), use the \a flags to
@@ -7705,7 +7724,7 @@ void QPainterState::init(QPainter *p) {
     \snippet code/src_gui_painting_qpainter.cpp 20
     \endtable
 
-    \sa drawPixmap()
+    \sa drawPixmap(), QImage::devicePixelRatio()
 */
 
 /*!