Introduce a flag to keep old image around while loading new one

With asynchronous image loading, you may see flickering when switching
between two images if they take longer than one frame to load. Working
around this involved creating a custom Qt Quick component containing two
Image components and then flipping between these.

This introduces a new property called "retainWhileLoading" which keeps
a copy of the old image around while the new one is being loaded and
only flips them when the new data is ready. The property is added to
Image and BorderImage.

Fixes: QTBUG-66713
Change-Id: Idf53bffdadbe60fd6f692b9e7ad1b841f2280156
Reviewed-by: Eirik Aavitsland <eirik.aavitsland@qt.io>

13 files changed, 197 insertions, 104 deletions

diff --git a/src/quick/items/qquickborderimage.cpp b/src/quick/items/qquickborderimage.cpp
index 40daf518d3..004f0491bd 100644
--- a/src/quick/items/qquickborderimage.cpp
+++ b/src/quick/items/qquickborderimage.cpp
@@ -400,11 +400,16 @@ void QQuickBorderImage::requestFinished()
 {
     Q_D(QQuickBorderImage);
 
-    const QSize impsize = d->pix.implicitSize();
+    if (d->pendingPix != d->currentPix) {
+        std::swap(d->pendingPix, d->currentPix);
+        d->pendingPix->clear(this); // Clear the old image
+    }
+
+    const QSize impsize = d->currentPix->implicitSize();
     setImplicitSize(impsize.width() / d->devicePixelRatio, impsize.height() / d->devicePixelRatio);
 
-    if (d->pix.isError()) {
-        qmlWarning(this) << d->pix.error();
+    if (d->currentPix->isError()) {
+        qmlWarning(this) << d->currentPix->error();
         d->setStatus(Error);
         d->setProgress(0);
     } else {
@@ -416,8 +421,8 @@ void QQuickBorderImage::requestFinished()
         d->oldSourceSize = sourceSize();
         emit sourceSizeChanged();
     }
-    if (d->frameCount != d->pix.frameCount()) {
-        d->frameCount = d->pix.frameCount();
+    if (d->frameCount != d->currentPix->frameCount()) {
+        d->frameCount = d->currentPix->frameCount();
         emit frameCountChanged();
     }
 
@@ -507,7 +512,7 @@ QSGNode *QQuickBorderImage::updatePaintNode(QSGNode *oldNode, UpdatePaintNodeDat
 {
     Q_D(QQuickBorderImage);
 
-    QSGTexture *texture = d->sceneGraphRenderContext()->textureForFactory(d->pix.textureFactory(), window());
+    QSGTexture *texture = d->sceneGraphRenderContext()->textureForFactory(d->currentPix->textureFactory(), window());
 
     if (!texture || width() <= 0 || height() <= 0) {
         delete oldNode;
@@ -532,7 +537,7 @@ QSGNode *QQuickBorderImage::updatePaintNode(QSGNode *oldNode, UpdatePaintNodeDat
     QRectF innerSourceRect;
     QRectF subSourceRect;
     d->calculateRects(d->border,
-                      QSize(d->pix.width(), d->pix.height()), QSizeF(width(), height()),
+                      QSize(d->currentPix->width(), d->currentPix->height()), QSizeF(width(), height()),
                       d->horizontalTileMode, d->verticalTileMode, d->devicePixelRatio,
                       &targetRect, &innerTargetRect,
                       &innerSourceRect, &subSourceRect);
@@ -577,6 +582,13 @@ void QQuickBorderImage::pixmapChange()
     frameCount is the number of frames in the image. Most images have only one frame.
 */
 
+/*!
+    \qmlproperty bool QtQuick::BorderImage::retainWhileLoading
+    \since 6.8
+
+    \include qquickimage.cpp qml-image-retainwhileloading
+ */
+
 QT_END_NAMESPACE
 
 #include "moc_qquickborderimage_p.cpp"
diff --git a/src/quick/items/qquickimage.cpp b/src/quick/items/qquickimage.cpp
index 3aaa59819c..3efe082332 100644
--- a/src/quick/items/qquickimage.cpp
+++ b/src/quick/items/qquickimage.cpp
@@ -218,7 +218,7 @@ QQuickImage::~QQuickImage()
 void QQuickImagePrivate::setImage(const QImage &image)
 {
     Q_Q(QQuickImage);
-    pix.setImage(image);
+    currentPix->setImage(image);
     q->pixmapChange();
     q->update();
 }
@@ -226,7 +226,7 @@ void QQuickImagePrivate::setImage(const QImage &image)
 void QQuickImagePrivate::setPixmap(const QQuickPixmap &pixmap)
 {
     Q_Q(QQuickImage);
-    pix.setPixmap(pixmap);
+    currentPix->setPixmap(pixmap);
     q->pixmapChange();
     q->update();
 }
@@ -605,12 +605,12 @@ void QQuickImage::updatePaintedGeometry()
     Q_D(QQuickImage);
 
     if (d->fillMode == PreserveAspectFit) {
-        if (!d->pix.width() || !d->pix.height()) {
+        if (!d->currentPix->width() || !d->currentPix->height()) {
             setImplicitSize(0, 0);
             return;
         }
-        const qreal pixWidth = d->pix.width() / d->devicePixelRatio;
-        const qreal pixHeight = d->pix.height() / d->devicePixelRatio;
+        const qreal pixWidth = d->currentPix->width() / d->devicePixelRatio;
+        const qreal pixHeight = d->currentPix->height() / d->devicePixelRatio;
         const qreal w = widthValid() ? width() : pixWidth;
         const qreal widthScale = w / pixWidth;
         const qreal h = heightValid() ? height() : pixHeight;
@@ -627,10 +627,10 @@ void QQuickImage::updatePaintedGeometry()
         setImplicitSize(iWidth, iHeight);
 
     } else if (d->fillMode == PreserveAspectCrop) {
-        if (!d->pix.width() || !d->pix.height())
+        if (!d->currentPix->width() || !d->currentPix->height())
             return;
-        const qreal pixWidth = d->pix.width() / d->devicePixelRatio;
-        const qreal pixHeight = d->pix.height() / d->devicePixelRatio;
+        const qreal pixWidth = d->currentPix->width() / d->devicePixelRatio;
+        const qreal pixHeight = d->currentPix->height() / d->devicePixelRatio;
         qreal widthScale = width() / pixWidth;
         qreal heightScale = height() / pixHeight;
         if (widthScale < heightScale) {
@@ -642,8 +642,8 @@ void QQuickImage::updatePaintedGeometry()
         d->paintedHeight = heightScale * pixHeight;
         d->paintedWidth = widthScale * pixWidth;
     } else if (d->fillMode == Pad) {
-        d->paintedWidth = d->pix.width() / d->devicePixelRatio;
-        d->paintedHeight = d->pix.height() / d->devicePixelRatio;
+        d->paintedWidth = d->currentPix->width() / d->devicePixelRatio;
+        d->paintedHeight = d->currentPix->height() / d->devicePixelRatio;
     } else {
         d->paintedWidth = width();
         d->paintedHeight = height();
@@ -685,7 +685,7 @@ QSGTextureProvider *QQuickImage::textureProvider() const
         dd->provider = new QQuickImageTextureProvider;
         dd->provider->m_smooth = d->smooth;
         dd->provider->m_mipmap = d->mipmap;
-        dd->provider->updateTexture(d->sceneGraphRenderContext()->textureForFactory(d->pix.textureFactory(), window()));
+        dd->provider->updateTexture(d->sceneGraphRenderContext()->textureForFactory(d->currentPix->textureFactory(), window()));
     }
 
     return d->provider;
@@ -711,7 +711,7 @@ QSGNode *QQuickImage::updatePaintNode(QSGNode *oldNode, UpdatePaintNodeData *)
 {
     Q_D(QQuickImage);
 
-    QSGTexture *texture = d->sceneGraphRenderContext()->textureForFactory(d->pix.textureFactory(), window());
+    QSGTexture *texture = d->sceneGraphRenderContext()->textureForFactory(d->currentPix->textureFactory(), window());
 
     // Copy over the current texture state into the texture provider...
     if (d->provider) {
@@ -736,8 +736,8 @@ QSGNode *QQuickImage::updatePaintNode(QSGNode *oldNode, UpdatePaintNodeData *)
     QSGTexture::WrapMode hWrap = QSGTexture::ClampToEdge;
     QSGTexture::WrapMode vWrap = QSGTexture::ClampToEdge;
 
-    qreal pixWidth = (d->fillMode == PreserveAspectFit) ? d->paintedWidth : d->pix.width() / d->devicePixelRatio;
-    qreal pixHeight = (d->fillMode == PreserveAspectFit) ? d->paintedHeight :  d->pix.height() / d->devicePixelRatio;
+    qreal pixWidth = (d->fillMode == PreserveAspectFit) ? d->paintedWidth : d->currentPix->width() / d->devicePixelRatio;
+    qreal pixHeight = (d->fillMode == PreserveAspectFit) ? d->paintedHeight :  d->currentPix->height() / d->devicePixelRatio;
 
     int xOffset = 0;
     if (d->hAlign == QQuickImage::AlignHCenter)
@@ -754,36 +754,36 @@ QSGNode *QQuickImage::updatePaintNode(QSGNode *oldNode, UpdatePaintNodeData *)
     switch (d->fillMode) {
     case Stretch:
         targetRect = QRectF(0, 0, width(), height());
-        sourceRect = d->pix.rect();
+        sourceRect = d->currentPix->rect();
         break;
 
     case PreserveAspectFit:
         targetRect = QRectF(xOffset, yOffset, d->paintedWidth, d->paintedHeight);
-        sourceRect = d->pix.rect();
+        sourceRect = d->currentPix->rect();
         break;
 
     case PreserveAspectCrop: {
         targetRect = QRectF(0, 0, width(), height());
-        qreal wscale = width() / qreal(d->pix.width());
-        qreal hscale = height() / qreal(d->pix.height());
+        qreal wscale = width() / qreal(d->currentPix->width());
+        qreal hscale = height() / qreal(d->currentPix->height());
 
         if (wscale > hscale) {
-            int src = (hscale / wscale) * qreal(d->pix.height());
+            int src = (hscale / wscale) * qreal(d->currentPix->height());
             int y = 0;
             if (d->vAlign == QQuickImage::AlignVCenter)
-                y = qCeil((d->pix.height() - src) / 2.);
+                y = qCeil((d->currentPix->height() - src) / 2.);
             else if (d->vAlign == QQuickImage::AlignBottom)
-                y = qCeil(d->pix.height() - src);
-            sourceRect = QRectF(0, y, d->pix.width(), src);
+                y = qCeil(d->currentPix->height() - src);
+            sourceRect = QRectF(0, y, d->currentPix->width(), src);
 
         } else {
-            int src = (wscale / hscale) * qreal(d->pix.width());
+            int src = (wscale / hscale) * qreal(d->currentPix->width());
             int x = 0;
             if (d->hAlign == QQuickImage::AlignHCenter)
-                x = qCeil((d->pix.width() - src) / 2.);
+                x = qCeil((d->currentPix->width() - src) / 2.);
             else if (d->hAlign == QQuickImage::AlignRight)
-                x = qCeil(d->pix.width() - src);
-            sourceRect = QRectF(x, 0, src, d->pix.height());
+                x = qCeil(d->currentPix->width() - src);
+            sourceRect = QRectF(x, 0, src, d->currentPix->height());
         }
         }
         break;
@@ -797,13 +797,13 @@ QSGNode *QQuickImage::updatePaintNode(QSGNode *oldNode, UpdatePaintNodeData *)
 
     case TileHorizontally:
         targetRect = QRectF(0, 0, width(), height());
-        sourceRect = QRectF(-xOffset, 0, width(), d->pix.height());
+        sourceRect = QRectF(-xOffset, 0, width(), d->currentPix->height());
         hWrap = QSGTexture::Repeat;
         break;
 
     case TileVertically:
         targetRect = QRectF(0, 0, width(), height());
-        sourceRect = QRectF(0, -yOffset, d->pix.width(), height());
+        sourceRect = QRectF(0, -yOffset, d->currentPix->width(), height());
         vWrap = QSGTexture::Repeat;
         break;
 
@@ -817,8 +817,8 @@ QSGNode *QQuickImage::updatePaintNode(QSGNode *oldNode, UpdatePaintNodeData *)
         break;
     }
 
-    qreal nsWidth = (hWrap == QSGTexture::Repeat || d->fillMode == Pad) ? d->pix.width() / d->devicePixelRatio : d->pix.width();
-    qreal nsHeight = (vWrap == QSGTexture::Repeat || d->fillMode == Pad) ? d->pix.height() / d->devicePixelRatio : d->pix.height();
+    qreal nsWidth = (hWrap == QSGTexture::Repeat || d->fillMode == Pad) ? d->currentPix->width() / d->devicePixelRatio : d->currentPix->width();
+    qreal nsHeight = (vWrap == QSGTexture::Repeat || d->fillMode == Pad) ? d->currentPix->height() / d->devicePixelRatio : d->currentPix->height();
     QRectF nsrect(sourceRect.x() / nsWidth,
                   sourceRect.y() / nsHeight,
                   sourceRect.width() / nsWidth,
@@ -967,6 +967,25 @@ void QQuickImage::setMipmap(bool use)
     frameCount is the number of frames in the image. Most images have only one frame.
 */
 
+/*!
+    \qmlproperty bool QtQuick::Image::retainWhileLoading
+    \since 6.8
+
+//! [qml-image-retainwhileloading]
+    This property defines the behavior when the \l source property is changed and loading happens
+    asynchronously. This is the case when the \l asynchronous property is set to \c true, or if the
+    image is not on the local file system.
+
+    If \c retainWhileLoading is \c false (the default), the old image is discarded immediately, and
+    the component is cleared while the new image is being loaded. If set to \c true, the old image
+    is retained and remains visible until the new one is ready.
+
+    Enabling this property can avoid flickering in cases where loading the new image takes a long
+    time. It comes at the cost of some extra memory use for double buffering while the new image is
+    being loaded.
+//! [qml-image-retainwhileloading]
+ */
+
 QT_END_NAMESPACE
 
 #include "moc_qquickimage_p_p.cpp"
diff --git a/src/quick/items/qquickimagebase.cpp b/src/quick/items/qquickimagebase.cpp
index bcc685d64c..61d6e90548 100644
--- a/src/quick/items/qquickimagebase.cpp
+++ b/src/quick/items/qquickimagebase.cpp
@@ -135,7 +135,7 @@ QSize QQuickImageBase::sourceSize() const
 
     int width = d->sourcesize.width();
     int height = d->sourcesize.height();
-    return QSize(width != -1 ? width : d->pix.width(), height != -1 ? height : d->pix.height());
+    return QSize(width != -1 ? width : d->currentPix->width(), height != -1 ? height : d->currentPix->height());
 }
 
 void QQuickImageBase::resetSourceSize()
@@ -188,7 +188,7 @@ void QQuickImageBase::setCache(bool cache)
 QImage QQuickImageBase::image() const
 {
     Q_D(const QQuickImageBase);
-    return d->pix.image();
+    return d->currentPix->image();
 }
 
 void QQuickImageBase::setMirror(bool mirror)
@@ -234,7 +234,7 @@ bool QQuickImageBase::mirrorVertically() const
 void QQuickImageBase::setCurrentFrame(int frame)
 {
     Q_D(QQuickImageBase);
-    if (frame == d->currentFrame || frame < 0 || (isComponentComplete() && frame >= d->pix.frameCount()))
+    if (frame == d->currentFrame || frame < 0 || (isComponentComplete() && frame >= d->currentPix->frameCount()))
         return;
 
     d->currentFrame = frame;
@@ -264,7 +264,8 @@ int QQuickImageBase::frameCount() const
 void QQuickImageBase::loadEmptyUrl()
 {
     Q_D(QQuickImageBase);
-    d->pix.clear(this);
+    d->currentPix->clear(this);
+    d->pendingPix->clear(this);
     d->setProgress(0);
     d->status = Null; // do not emit statusChanged until after setImplicitSize
     setImplicitSize(0, 0); // also called in QQuickImageBase::pixmapChange, but not QQuickImage/QQuickBorderImage overrides
@@ -290,7 +291,7 @@ void QQuickImageBase::loadPixmap(const QUrl &url, LoadPixmapOptions loadOptions)
         options |= QQuickPixmap::Asynchronous;
     if (d->cache)
         options |= QQuickPixmap::Cache;
-    d->pix.clear(this);
+    d->pendingPix->clear(this);
     QUrl loadUrl = url;
     const QQmlContext *context = qmlContext(this);
     if (context)
@@ -315,16 +316,16 @@ void QQuickImageBase::loadPixmap(const QUrl &url, LoadPixmapOptions loadOptions)
 
     d->status = Null; // reset status, no emit
 
-    d->pix.load(qmlEngine(this),
-                loadUrl,
-                d->sourceClipRect.toRect(),
-                (loadOptions & HandleDPR) ? d->sourcesize * d->devicePixelRatio : QSize(),
-                options,
-                (loadOptions & UseProviderOptions) ? d->providerOptions : QQuickImageProviderOptions(),
-                d->currentFrame, d->frameCount,
-                d->devicePixelRatio);
+    d->pendingPix->load(qmlEngine(this),
+                        loadUrl,
+                        d->sourceClipRect.toRect(),
+                        (loadOptions & HandleDPR) ? d->sourcesize * d->devicePixelRatio : QSize(),
+                        options,
+                        (loadOptions & UseProviderOptions) ? d->providerOptions : QQuickImageProviderOptions(),
+                        d->currentFrame, d->frameCount,
+                        d->devicePixelRatio);
 
-    if (d->pix.isLoading()) {
+    if (d->pendingPix->isLoading()) {
         d->setProgress(0);
         d->setStatus(Loading);
 
@@ -337,9 +338,10 @@ void QQuickImageBase::loadPixmap(const QUrl &url, LoadPixmapOptions loadOptions)
                 QQuickImageBase::staticMetaObject.indexOfSlot("requestFinished()");
         }
 
-        d->pix.connectFinished(this, thisRequestFinished);
-        d->pix.connectDownloadProgress(this, thisRequestProgress);
-        update(); //pixmap may have invalidated texture, updatePaintNode needs to be called before the next repaint
+        d->pendingPix->connectFinished(this, thisRequestFinished);
+        d->pendingPix->connectDownloadProgress(this, thisRequestProgress);
+        if (!d->retainWhileLoading)
+            update(); //pixmap may have invalidated texture, updatePaintNode needs to be called before the next repaint
     } else {
         requestFinished();
     }
@@ -361,9 +363,13 @@ void QQuickImageBase::requestFinished()
 {
     Q_D(QQuickImageBase);
 
-    if (d->pix.isError()) {
-        qmlWarning(this) << d->pix.error();
-        d->pix.clear(this);
+    if (d->pendingPix != d->currentPix) {
+        std::swap(d->pendingPix, d->currentPix);
+        d->pendingPix->clear(this); // Clear the old image
+    }
+
+    if (d->currentPix->isError()) {
+        qmlWarning(this) << d->currentPix->error();
         d->status = Error;
         d->setProgress(0);
     } else {
@@ -382,12 +388,12 @@ void QQuickImageBase::requestFinished()
         d->oldAutoTransform = autoTransform();
         emitAutoTransformBaseChanged();
     }
-    if (d->frameCount != d->pix.frameCount()) {
-        d->frameCount = d->pix.frameCount();
+    if (d->frameCount != d->currentPix->frameCount()) {
+        d->frameCount = d->currentPix->frameCount();
         emit frameCountChanged();
     }
-    if (d->colorSpace != d->pix.colorSpace()) {
-        d->colorSpace = d->pix.colorSpace();
+    if (d->colorSpace != d->currentPix->colorSpace()) {
+        d->colorSpace = d->currentPix->colorSpace();
         emit colorSpaceChanged();
     }
 
@@ -430,7 +436,7 @@ void QQuickImageBase::componentComplete()
 void QQuickImageBase::pixmapChange()
 {
     Q_D(QQuickImageBase);
-    setImplicitSize(d->pix.width() / d->devicePixelRatio, d->pix.height() / d->devicePixelRatio);
+    setImplicitSize(d->currentPix->width() / d->devicePixelRatio, d->currentPix->height() / d->devicePixelRatio);
 }
 
 void QQuickImageBase::resolve2xLocalFile(const QUrl &url, qreal targetDevicePixelRatio, QUrl *sourceUrl, qreal *sourceDevicePixelRatio)
@@ -470,7 +476,7 @@ bool QQuickImageBase::autoTransform() const
 {
     Q_D(const QQuickImageBase);
     if (d->providerOptions.autoTransform() == QQuickImageProviderOptions::UsePluginDefaultTransform)
-        return d->pix.autoTransform() == QQuickImageProviderOptions::ApplyTransform;
+        return d->currentPix->autoTransform() == QQuickImageProviderOptions::ApplyTransform;
     return d->providerOptions.autoTransform() == QQuickImageProviderOptions::ApplyTransform;
 }
 
@@ -500,6 +506,30 @@ void QQuickImageBase::setColorSpace(const QColorSpace &colorSpace)
     emit colorSpaceChanged();
 }
 
+bool QQuickImageBase::retainWhileLoading() const
+{
+    Q_D(const QQuickImageBase);
+    return d->retainWhileLoading;
+}
+
+void QQuickImageBase::setRetainWhileLoading(bool retainWhileLoading)
+{
+    Q_D(QQuickImageBase);
+    if (d->retainWhileLoading == retainWhileLoading)
+        return;
+
+    d->retainWhileLoading = retainWhileLoading;
+    if (d->retainWhileLoading) {
+        if (d->currentPix == &d->pix1)
+            d->pendingPix = &d->pix2;
+        else
+            d->pendingPix = &d->pix1;
+    } else {
+        d->pendingPix->clear();
+        d->pendingPix = d->currentPix;
+    }
+}
+
 QT_END_NAMESPACE
 
 #include "moc_qquickimagebase_p.cpp"
diff --git a/src/quick/items/qquickimagebase_p.h b/src/quick/items/qquickimagebase_p.h
index 08f9abbc63..5a33db43b8 100644
--- a/src/quick/items/qquickimagebase_p.h
+++ b/src/quick/items/qquickimagebase_p.h
@@ -33,6 +33,7 @@ class Q_QUICK_EXPORT QQuickImageBase : public QQuickImplicitSizeItem
     Q_PROPERTY(bool cache READ cache WRITE setCache NOTIFY cacheChanged)
     Q_PROPERTY(bool mirror READ mirror WRITE setMirror NOTIFY mirrorChanged)
     Q_PROPERTY(bool mirrorVertically READ mirrorVertically WRITE setMirrorVertically NOTIFY mirrorVerticallyChanged REVISION(6, 2))
+    Q_PROPERTY(bool retainWhileLoading READ retainWhileLoading WRITE setRetainWhileLoading NOTIFY retainWhileLoadingChanged REVISION(6, 8))
     Q_PROPERTY(int currentFrame READ currentFrame WRITE setCurrentFrame NOTIFY currentFrameChanged REVISION(2, 14))
     Q_PROPERTY(int frameCount READ frameCount NOTIFY frameCountChanged REVISION(2, 14))
     Q_PROPERTY(QColorSpace colorSpace READ colorSpace WRITE setColorSpace NOTIFY colorSpaceChanged REVISION(2, 15))
@@ -94,6 +95,9 @@ public:
     QColorSpace colorSpace() const;
     virtual void setColorSpace(const QColorSpace &colorSpace);
 
+    bool retainWhileLoading() const;
+    void setRetainWhileLoading(bool retain);
+
     static void resolve2xLocalFile(const QUrl &url, qreal targetDevicePixelRatio, QUrl *sourceUrl, qreal *sourceDevicePixelRatio);
 
     // Use a virtual rather than a signal->signal to avoid the huge
@@ -113,6 +117,7 @@ Q_SIGNALS:
     Q_REVISION(2, 15) void sourceClipRectChanged();
     Q_REVISION(2, 15) void colorSpaceChanged();
     Q_REVISION(6, 2) void mirrorVerticallyChanged();
+    Q_REVISION(6, 8) void retainWhileLoadingChanged();
 
 protected:
     void loadEmptyUrl();
diff --git a/src/quick/items/qquickimagebase_p_p.h b/src/quick/items/qquickimagebase_p_p.h
index 3cbb9facb0..d53712b779 100644
--- a/src/quick/items/qquickimagebase_p_p.h
+++ b/src/quick/items/qquickimagebase_p_p.h
@@ -33,8 +33,11 @@ public:
         cache(true),
         mirrorHorizontally(false),
         mirrorVertically(false),
-        oldAutoTransform(false)
+        oldAutoTransform(false),
+        retainWhileLoading(false)
     {
+        pendingPix = &pix1;
+        currentPix = &pix1;
     }
 
     virtual bool updateDevicePixelRatio(qreal targetDevicePixelRatio);
@@ -43,7 +46,10 @@ public:
     void setProgress(qreal value);
 
     QUrl url;
-    QQuickPixmap pix;
+    QQuickPixmap *pendingPix = nullptr;
+    QQuickPixmap *currentPix = nullptr;
+    QQuickPixmap pix1;
+    QQuickPixmap pix2;
     QSize sourcesize;
     QSize oldSourceSize;
     QRectF sourceClipRect;
@@ -61,6 +67,7 @@ public:
     bool mirrorHorizontally: 1;
     bool mirrorVertically : 1;
     bool oldAutoTransform : 1;
+    bool retainWhileLoading : 1;
 };
 
 QT_END_NAMESPACE
diff --git a/src/quickcontrolsimpl/qquickcolorimage.cpp b/src/quickcontrolsimpl/qquickcolorimage.cpp
index 5ad6d7d296..dcd87b5e72 100644
--- a/src/quickcontrolsimpl/qquickcolorimage.cpp
+++ b/src/quickcontrolsimpl/qquickcolorimage.cpp
@@ -57,12 +57,12 @@ void QQuickColorImage::pixmapChange()
     QQuickImage::pixmapChange();
     if (m_color.alpha() > 0 && m_color != m_defaultColor) {
         QQuickImageBasePrivate *d = static_cast<QQuickImageBasePrivate *>(QQuickItemPrivate::get(this));
-        QImage image = d->pix.image();
+        QImage image = d->currentPix->image();
         if (!image.isNull()) {
             QPainter painter(&image);
             painter.setCompositionMode(QPainter::CompositionMode_SourceIn);
             painter.fillRect(image.rect(), m_color);
-            d->pix.setImage(image);
+            d->currentPix->setImage(image);
         }
     }
 }
diff --git a/src/quickcontrolsimpl/qquickiconimage.cpp b/src/quickcontrolsimpl/qquickiconimage.cpp
index 24bb752ebd..c2af3e0539 100644
--- a/src/quickcontrolsimpl/qquickiconimage.cpp
+++ b/src/quickcontrolsimpl/qquickiconimage.cpp
@@ -82,7 +82,7 @@ void QQuickIconImagePrivate::updateFillMode()
 
     updatingFillMode = true;
 
-    const QSize pixmapSize = QSize(pix.width(), pix.height()) / calculateDevicePixelRatio();
+    const QSize pixmapSize = QSize(currentPix->width(), currentPix->height()) / calculateDevicePixelRatio();
     if (pixmapSize.width() > q->width() || pixmapSize.height() > q->height())
         q->setFillMode(QQuickImage::PreserveAspectFit);
     else
@@ -186,12 +186,12 @@ void QQuickIconImage::pixmapChange()
 
     // Don't apply the color if we're recursing (updateFillMode() can cause us to recurse).
     if (!d->updatingFillMode && d->color.alpha() > 0) {
-        QImage image = d->pix.image();
+        QImage image = d->currentPix->image();
         if (!image.isNull()) {
             QPainter painter(&image);
             painter.setCompositionMode(QPainter::CompositionMode_SourceIn);
             painter.fillRect(image.rect(), d->color);
-            d->pix.setImage(image);
+            d->currentPix->setImage(image);
         }
     }
 }
diff --git a/src/quickcontrolsimpl/qquickninepatchimage.cpp b/src/quickcontrolsimpl/qquickninepatchimage.cpp
index d6238d2ccd..4d34123014 100644
--- a/src/quickcontrolsimpl/qquickninepatchimage.cpp
+++ b/src/quickcontrolsimpl/qquickninepatchimage.cpp
@@ -399,13 +399,13 @@ void QQuickNinePatchImage::pixmapChange()
         if (!d->resetNode)
             d->resetNode = d->ninePatch.isNull();
 
-        d->ninePatch = d->pix.image();
+        d->ninePatch = d->currentPix->image();
         if (d->ninePatch.depth() != 32)
             d->ninePatch = std::move(d->ninePatch).convertToFormat(QImage::Format_ARGB32);
 
         int w = d->ninePatch.width();
         int h = d->ninePatch.height();
-        d->pix.setImage(QImage(d->ninePatch.constBits() + 4 * (w + 1), w - 2, h - 2, d->ninePatch.bytesPerLine(), d->ninePatch.format()));
+        d->currentPix->setImage(QImage(d->ninePatch.constBits() + 4 * (w + 1), w - 2, h - 2, d->ninePatch.bytesPerLine(), d->ninePatch.format()));
 
         d->updatePatches();
     } else {
@@ -447,7 +447,7 @@ QSGNode *QQuickNinePatchImage::updatePaintNode(QSGNode *oldNode, UpdatePaintNode
         return QQuickImage::updatePaintNode(oldNode, data);
 
     QSizeF sz = size();
-    QImage image = d->pix.image();
+    QImage image = d->currentPix->image();
     if (!sz.isValid() || image.isNull()) {
         if (d->provider)
             d->provider->updateTexture(nullptr);
diff --git a/src/quickvectorimage/generator/qquickitemgenerator.cpp b/src/quickvectorimage/generator/qquickitemgenerator.cpp
index 171cb6889f..3425ecc13b 100644
--- a/src/quickvectorimage/generator/qquickitemgenerator.cpp
+++ b/src/quickvectorimage/generator/qquickitemgenerator.cpp
@@ -75,7 +75,7 @@ void QQuickItemGenerator::generateImageNode(const ImageNodeInfo &info)
 
     auto *imageItem = new QQuickImage;
     auto *imagePriv = static_cast<QQuickImageBasePrivate*>(QQuickItemPrivate::get(imageItem));
-    imagePriv->pix.setImage(info.image);
+    imagePriv->currentPix->setImage(info.image);
 
     imageItem->setX(info.rect.x());
     imageItem->setY(info.rect.y());
diff --git a/tests/auto/quick/qquickimage/data/multiframeAsyncRetain.qml b/tests/auto/quick/qquickimage/data/multiframeAsyncRetain.qml
new file mode 100644
index 0000000000..fc0f135528
--- /dev/null
+++ b/tests/auto/quick/qquickimage/data/multiframeAsyncRetain.qml
@@ -0,0 +1,7 @@
+import QtQuick
+
+Image {
+    source: "multi.ico"
+    asynchronous: true
+    retainWhileLoading: true
+}
diff --git a/tests/auto/quick/qquickimage/tst_qquickimage.cpp b/tests/auto/quick/qquickimage/tst_qquickimage.cpp
index 427a45977f..d19c99de82 100644
--- a/tests/auto/quick/qquickimage/tst_qquickimage.cpp
+++ b/tests/auto/quick/qquickimage/tst_qquickimage.cpp
@@ -135,41 +135,49 @@ void tst_qquickimage::imageSource_data()
     QTest::addColumn<bool>("async");
     QTest::addColumn<bool>("cache");
     QTest::addColumn<QString>("error");
+    QTest::addColumn<bool>("retainWhileLoading");
 
-    QTest::newRow("local") << testFileUrl("colors.png").toString() << 120.0 << 120.0 << false << false << true << "";
-    QTest::newRow("local no cache") << testFileUrl("colors.png").toString() << 120.0 << 120.0 << false << false << false << "";
-    QTest::newRow("local async") << testFileUrl("colors1.png").toString() << 120.0 << 120.0 << false << true << true << "";
+    QTest::newRow("local") << testFileUrl("colors.png").toString() << 120.0 << 120.0 << false << false << true << "" << false;
+    QTest::newRow("local no cache") << testFileUrl("colors.png").toString() << 120.0 << 120.0 << false << false << false << "" << false;
+    QTest::newRow("local async") << testFileUrl("colors1.png").toString() << 120.0 << 120.0 << false << true << true << "" << false;
+    QTest::newRow("local async retain") << testFileUrl("colors1.png").toString() << 120.0 << 120.0 << false << true << true << "" << true;
     QTest::newRow("local not found") << testFileUrl("no-such-file.png").toString() << 0.0 << 0.0 << false
-        << false << true << "<Unknown File>:2:1: QML Image: Cannot open: " + testFileUrl("no-such-file.png").toString();
+        << false << true << "<Unknown File>:2:1: QML Image: Cannot open: " + testFileUrl("no-such-file.png").toString() << false;
     QTest::newRow("local async not found") << testFileUrl("no-such-file-1.png").toString() << 0.0 << 0.0 << false
-        << true << true << "<Unknown File>:2:1: QML Image: Cannot open: " + testFileUrl("no-such-file-1.png").toString();
-    QTest::newRow("remote") << "/colors.png" << 120.0 << 120.0 << true << false << true << "";
-    QTest::newRow("remote redirected") << "/oldcolors.png" << 120.0 << 120.0 << true << false << false << "";
+        << true << true << "<Unknown File>:2:1: QML Image: Cannot open: " + testFileUrl("no-such-file-1.png").toString() << false;
+    QTest::newRow("local async retain not found") << testFileUrl("no-such-file-1.png").toString() << 0.0 << 0.0 << false
+                                           << true << true << "<Unknown File>:2:1: QML Image: Cannot open: " + testFileUrl("no-such-file-1.png").toString() << true;
+    QTest::newRow("remote") << "/colors.png" << 120.0 << 120.0 << true << false << true << "" << false;
+    QTest::newRow("remote retain") << "/colors.png" << 120.0 << 120.0 << true << false << true << "" << true;
+    QTest::newRow("remote redirected") << "/oldcolors.png" << 120.0 << 120.0 << true << false << false << "" << false;
     if (QImageReader::supportedImageFormats().contains("svg"))
-        QTest::newRow("remote svg") << "/heart.svg" << 595.0 << 841.0 << true << false << false << "";
+        QTest::newRow("remote svg") << "/heart.svg" << 595.0 << 841.0 << true << false << false << "" << false;
     if (QImageReader::supportedImageFormats().contains("svgz"))
-        QTest::newRow("remote svgz") << "/heart.svgz" << 595.0 << 841.0 << true << false << false << "";
+        QTest::newRow("remote svgz") << "/heart.svgz" << 595.0 << 841.0 << true << false << false << "" << false;
     if (graphicsApi != QSGRendererInterface::Software) {
-        QTest::newRow("texturefile pkm format") << testFileUrl("logo.pkm").toString() << 256.0 << 256.0 << false << false << true << "";
-        QTest::newRow("texturefile ktx format") << testFileUrl("car.ktx").toString() << 146.0 << 80.0 << false << false << true << "";
-        QTest::newRow("texturefile async") << testFileUrl("logo.pkm").toString() << 256.0 << 256.0 << false << true << true << "";
-        QTest::newRow("texturefile remote") << "/logo.pkm" << 256.0 << 256.0 << true << false << true << "";
+        QTest::newRow("texturefile pkm format") << testFileUrl("logo.pkm").toString() << 256.0 << 256.0 << false << false << true << "" << false;
+        QTest::newRow("texturefile ktx format") << testFileUrl("car.ktx").toString() << 146.0 << 80.0 << false << false << true << "" << false;
+        QTest::newRow("texturefile async") << testFileUrl("logo.pkm").toString() << 256.0 << 256.0 << false << true << true << "" << false;
+        QTest::newRow("texturefile async retain") << testFileUrl("logo.pkm").toString() << 256.0 << 256.0 << false << true << true << "" << true;
+        QTest::newRow("texturefile remote") << "/logo.pkm" << 256.0 << 256.0 << true << false << true << "" << false;
+        QTest::newRow("texturefile remote retain") << "/logo.pkm" << 256.0 << 256.0 << true << false << true << "" << true;
     }
     QTest::newRow("remote not found") << "/no-such-file.png" << 0.0 << 0.0 << true
-        << false << true << "<Unknown File>:2:1: QML Image: Error transferring {{ServerBaseUrl}}/no-such-file.png - server replied: Not found";
-    QTest::newRow("extless") << testFileUrl("colors").toString() << 120.0 << 120.0 << false << false << true << "";
-    QTest::newRow("extless no cache") << testFileUrl("colors").toString() << 120.0 << 120.0 << false << false << false << "";
-    QTest::newRow("extless async") << testFileUrl("colors1").toString() << 120.0 << 120.0 << false << true << true << "";
+        << false << true << "<Unknown File>:2:1: QML Image: Error transferring {{ServerBaseUrl}}/no-such-file.png - server replied: Not found" << false;
+    QTest::newRow("extless") << testFileUrl("colors").toString() << 120.0 << 120.0 << false << false << true << "" << false;
+    QTest::newRow("extless no cache") << testFileUrl("colors").toString() << 120.0 << 120.0 << false << false << false << "" << false;
+    QTest::newRow("extless async") << testFileUrl("colors1").toString() << 120.0 << 120.0 << false << true << true << "" << false;
+    QTest::newRow("extless async retain") << testFileUrl("colors1").toString() << 120.0 << 120.0 << false << true << true << "" << true;
     QTest::newRow("extless not found") << testFileUrl("no-such-file").toString() << 0.0 << 0.0 << false
-        << false << true << "<Unknown File>:2:1: QML Image: Cannot open: " + testFileUrl("no-such-file").toString();
+        << false << true << "<Unknown File>:2:1: QML Image: Cannot open: " + testFileUrl("no-such-file").toString() << false;
     // Test that texture file is preferred over image file, when supported.
     // Since pattern.pkm has different size than pattern.png, these tests verify that the right file has been loaded
     if (graphicsApi != QSGRendererInterface::Software) {
-        QTest::newRow("extless prefer-tex") << testFileUrl("pattern").toString() << 64.0 << 64.0 << false << false << true << "";
-        QTest::newRow("extless prefer-tex async") << testFileUrl("pattern").toString() << 64.0 << 64.0 << false << true << true << "";
+        QTest::newRow("extless prefer-tex") << testFileUrl("pattern").toString() << 64.0 << 64.0 << false << false << true << "" << false;
+        QTest::newRow("extless prefer-tex async") << testFileUrl("pattern").toString() << 64.0 << 64.0 << false << true << true << "" << false;
     } else {
-        QTest::newRow("extless ignore-tex") << testFileUrl("pattern").toString() << 200.0 << 200.0 << false << false << true << "";
-        QTest::newRow("extless ignore-tex async") << testFileUrl("pattern").toString() << 200.0 << 200.0 << false << true << true << "";
+        QTest::newRow("extless ignore-tex") << testFileUrl("pattern").toString() << 200.0 << 200.0 << false << false << true << "" << false;
+        QTest::newRow("extless ignore-tex async") << testFileUrl("pattern").toString() << 200.0 << 200.0 << false << true << true << "" << false;
     }
 
 }
@@ -183,6 +191,7 @@ void tst_qquickimage::imageSource()
     QFETCH(bool, async);
     QFETCH(bool, cache);
     QFETCH(QString, error);
+    QFETCH(bool, retainWhileLoading);
 
     TestHTTPServer server;
     if (remote) {
@@ -196,9 +205,10 @@ void tst_qquickimage::imageSource()
     if (!error.isEmpty())
         QTest::ignoreMessage(QtWarningMsg, error.toUtf8());
 
-    QString componentStr = "import QtQuick 2.0\nImage { source: \"" + source + "\"; asynchronous: "
+    QString componentStr = "import QtQuick\nImage { source: \"" + source + "\"; asynchronous: "
         + (async ? QLatin1String("true") : QLatin1String("false")) + "; cache: "
-        + (cache ? QLatin1String("true") : QLatin1String("false")) + " }";
+        + (cache ? QLatin1String("true") : QLatin1String("false")) + "; retainWhileLoading: "
+                           + (retainWhileLoading ? QLatin1String("true") : QLatin1String("false")) + " }";
     QQmlComponent component(&engine);
     component.setData(componentStr.toLatin1(), QUrl::fromLocalFile(""));
     QQuickImage *obj = qobject_cast<QQuickImage*>(component.create());
@@ -209,6 +219,8 @@ void tst_qquickimage::imageSource()
     else
         QVERIFY(!obj->asynchronous());
 
+    QCOMPARE(obj->retainWhileLoading(), retainWhileLoading);
+
     if (cache)
         QVERIFY(obj->cache());
     else
@@ -1208,6 +1220,7 @@ void tst_qquickimage::multiFrame_data()
 
     QTest::addRow("default") << "multiframe.qml" << false;
     QTest::addRow("async") << "multiframeAsync.qml" << true;
+    QTest::addRow("async retain") << "multiframeAsyncRetain.qml" << true;
 }
 
 void tst_qquickimage::multiFrame()
diff --git a/tests/auto/quick/qquickpixmapcache/deviceloadingimage.cpp b/tests/auto/quick/qquickpixmapcache/deviceloadingimage.cpp
index 72a956d1d2..65c8a11a2e 100644
--- a/tests/auto/quick/qquickpixmapcache/deviceloadingimage.cpp
+++ b/tests/auto/quick/qquickpixmapcache/deviceloadingimage.cpp
@@ -19,25 +19,25 @@ void DeviceLoadingImage::load()
     Q_ASSERT(context);
     QUrl resolved = context->resolvedUrl(d->url);
     device = std::make_unique<QFile>(resolved.toLocalFile());
-    d->pix.loadImageFromDevice(qmlEngine(this), device.get(), context->resolvedUrl(d->url),
+    d->pix1.loadImageFromDevice(qmlEngine(this), device.get(), context->resolvedUrl(d->url),
                                d->sourceClipRect.toRect(), d->sourcesize * d->devicePixelRatio,
                                QQuickImageProviderOptions(), d->currentFrame, d->frameCount);
 
-    qCDebug(lcTests) << "loading page" << d->currentFrame << "of" << d->frameCount << "status" << d->pix.status();
+    qCDebug(lcTests) << "loading page" << d->currentFrame << "of" << d->frameCount << "status" << d->pix1.status();
 
-    switch (d->pix.status()) {
+    switch (d->pix1.status()) {
     case QQuickPixmap::Ready:
         pixmapChange();
         break;
     case QQuickPixmap::Loading:
-        d->pix.connectFinished(this, thisRequestFinished);
+        d->pix1.connectFinished(this, thisRequestFinished);
         if (d->status != Loading) {
             d->status = Loading;
             emit statusChanged(d->status);
         }
         break;
     default:
-        qCWarning(lcTests) << "unexpected status" << d->pix.status();
+        qCWarning(lcTests) << "unexpected status" << d->pix1.status();
         break;
     }
 }
diff --git a/tests/auto/quickcontrols/qquickiconlabel/tst_qquickiconlabel.cpp b/tests/auto/quickcontrols/qquickiconlabel/tst_qquickiconlabel.cpp
index 9f0feb5139..c263fbe1bd 100644
--- a/tests/auto/quickcontrols/qquickiconlabel/tst_qquickiconlabel.cpp
+++ b/tests/auto/quickcontrols/qquickiconlabel/tst_qquickiconlabel.cpp
@@ -336,7 +336,7 @@ void tst_qquickiconlabel::iconSourceContext()
         QVERIFY(image);
         QQuickImagePrivate *imagePrivate
                 = static_cast<QQuickImagePrivate *>(QQuickItemPrivate::get(image));
-        QCOMPARE(imagePrivate->pix.url(), testFileUrl("a.png"));
+        QCOMPARE(imagePrivate->pix1.url(), testFileUrl("a.png"));
     }
 #endif
 }