diff options
author | Friedemann Kleint <Friedemann.Kleint@digia.com> | 2014-08-26 09:23:43 +0200 |
---|---|---|
committer | Friedemann Kleint <Friedemann.Kleint@digia.com> | 2014-08-26 16:59:36 +0200 |
commit | f85f3acd7878f49f0878644905ca27ceb7bc0775 (patch) | |
tree | cd193a95ea5c9ef35b1570cc7fc163b0cc8d38c5 | |
parent | 4017605d56f5e7769c6aa7954a285563c06646ad (diff) |
Document loading of high resolution versions of images.
Task-number: QTBUG-38858
Change-Id: I87ee18b66e137f5f5c01d77910f1a7f256b85e18
Reviewed-by: Alessandro Portale <alessandro.portale@digia.com>
-rw-r--r-- | src/gui/image/qicon.cpp | 10 | ||||
-rw-r--r-- | src/gui/image/qimage.cpp | 7 | ||||
-rw-r--r-- | src/gui/image/qimagereader.cpp | 14 | ||||
-rw-r--r-- | src/gui/image/qpixmap.cpp | 7 | ||||
-rw-r--r-- | src/gui/painting/qpainter.cpp | 31 |
5 files changed, 55 insertions, 14 deletions
diff --git a/src/gui/image/qicon.cpp b/src/gui/image/qicon.cpp index ac95222c99..1e4a9ebe8c 100644 --- a/src/gui/image/qicon.cpp +++ b/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) { diff --git a/src/gui/image/qimage.cpp b/src/gui/image/qimage.cpp index 16696f611d..c3b4b1444a 100644 --- a/src/gui/image/qimage.cpp +++ b/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() */ diff --git a/src/gui/image/qimagereader.cpp b/src/gui/image/qimagereader.cpp index 3c75202766..3bf002373c 100644 --- a/src/gui/image/qimagereader.cpp +++ b/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 */ /*! diff --git a/src/gui/image/qpixmap.cpp b/src/gui/image/qpixmap.cpp index 2d41ca7e24..88ce48f0e8 100644 --- a/src/gui/image/qpixmap.cpp +++ b/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() */ diff --git a/src/gui/painting/qpainter.cpp b/src/gui/painting/qpainter.cpp index 0e03a0194a..5d046caaa4 100644 --- a/src/gui/painting/qpainter.cpp +++ b/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() */ /*! |