Introduce QImage::reinterpretAsFormat

QImage::reinterpretAsFormat can be used to change the format of an image
without converting the data, to correct wrong formats or narrow the
format to an opaque one if found to be opaque.

[ChangeLog][QtGui][QImage] A new method reinterpretAsFormat is has been
added to change the format of a QImage without converting the data.

Change-Id: I5e15bc5a1c474a35d3921b06299008ab2effd945
Reviewed-by: Laszlo Agocs <laszlo.agocs@qt.io>
Reviewed-by: Eirik Aavitsland <eirik.aavitsland@qt.io>

2 files changed, 39 insertions, 0 deletions

diff --git a/src/gui/image/qimage.cpp b/src/gui/image/qimage.cpp
index b1dcf6a9f8..9870e19cec 100644
--- a/src/gui/image/qimage.cpp
+++ b/src/gui/image/qimage.cpp
@@ -2121,6 +2121,44 @@ QImage QImage::convertToFormat(Format format, const QVector<QRgb> &colorTable, Q
 }
 
 /*!
+    \since 5.9
+
+    Changes the format of the image without changing the data. Only
+    works between formats of the same depth.
+
+    Returns \c true if successful.
+
+    This function can be used to change images with alpha-channels to
+    their corresponding opaque formats if the data is known to be opaque-only,
+    or to change the format of a given image buffer before overwriting
+    it with new data.
+
+    \warning The function does not check if the image data is valid in the
+    new format and will still return \c true if the depths are compatible.
+    Operations on an image with invalid data are undefined.
+
+    \warning If the image is not detached, this will cause the data to be
+    copied.
+
+    \sa isDetached(), hasAlphaChannel(), convertToFormat()
+*/
+
+bool QImage::reinterpretAsFormat(Format format)
+{
+    if (!d)
+        return false;
+    if (d->format == format)
+        return true;
+    if (qt_depthForFormat(format) != qt_depthForFormat(d->format))
+        return false;
+    if (!isDetached()) // Detach only if shared, not for read-only data.
+        detach();
+
+    d->format = format;
+    return true;
+}
+
+/*!
     \fn bool QImage::valid(const QPoint &pos) const
 
     Returns \c true if \a pos is a valid coordinate pair within the
diff --git a/src/gui/image/qimage.h b/src/gui/image/qimage.h
index fd2298561e..204e7a54b2 100644
--- a/src/gui/image/qimage.h
+++ b/src/gui/image/qimage.h
@@ -192,6 +192,7 @@ public:
     QImage convertToFormat(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) const Q_REQUIRED_RESULT;
 #endif
     QImage convertToFormat(Format f, const QVector<QRgb> &colorTable, Qt::ImageConversionFlags flags = Qt::AutoColor) const Q_REQUIRED_RESULT;
+    bool reinterpretAsFormat(Format f);
 
     int width() const;
     int height() const;