QGraphicsItem: clarify the documentation about caching modes and update()

It is possible that Qt calls paint() several times for an item that
has caching enabled, even without any explicit call to update(). There
are various reasons why that is possible (memory pressure, item gets
transformed, etc.); the important part is that

1) the user must not rely into "caching enabled" = "1 paint() call"
2) the user must always draw the same content from within paint(),
unless update() was called before that call to paint().

Task-number: QTBUG-18410
Change-Id: I2c8d77e6e11aaceffc9a21003dd3f4cc46edd582
Reviewed-by: Venugopal Shivashankar <venugopal.shivashankar@digia.com>
Reviewed-by: Andy Shaw <andy.shaw@digia.com>

1 files changed, 20 insertions, 2 deletions

diff --git a/src/widgets/graphicsview/qgraphicsitem.cpp b/src/widgets/graphicsview/qgraphicsitem.cpp
index 76a75dfc35..300e2f492b 100644
--- a/src/widgets/graphicsview/qgraphicsitem.cpp
+++ b/src/widgets/graphicsview/qgraphicsitem.cpp
@@ -1968,8 +1968,10 @@ QGraphicsItem::CacheMode QGraphicsItem::cacheMode() const
     Caching can speed up rendering if your item spends a significant time
     redrawing itself. In some cases the cache can also slow down rendering, in
     particular when the item spends less time redrawing than QGraphicsItem
-    spends redrawing from the cache. When enabled, the item's paint() function
-    will be called only once for each call to update(); for any subsequent
+    spends redrawing from the cache.
+
+    When caching is enabled, an item's paint() function will generally draw into an
+    offscreen pixmap cache; for any subsequent
     repaint requests, the Graphics View framework will redraw from the
     cache. This approach works particularly well with QGLWidget, which stores
     all the cache as OpenGL textures.
@@ -1980,6 +1982,12 @@ QGraphicsItem::CacheMode QGraphicsItem::cacheMode() const
     You can read more about the different cache modes in the CacheMode
     documentation.
 
+    \note Enabling caching does not imply that the item's paint() function will be
+    called only in response to an explicit update() call. For instance, under
+    memory pressure, Qt may decide to drop some of the cache information;
+    in such cases an item's paint() function will be called even if there
+    was no update() call (that is, exactly as if there were no caching enabled).
+
     \sa CacheMode, QPixmapCache::setCacheLimit()
 */
 void QGraphicsItem::setCacheMode(CacheMode mode, const QSize &logicalCacheSize)
@@ -5337,6 +5345,16 @@ void QGraphicsItem::setBoundingRegionGranularity(qreal granularity)
 
     All painting is done in local coordinates.
 
+    \note It is mandatory that an item will always redraw itself in the exact
+    same way, unless update() was called; otherwise visual artifacts may
+    occur. In other words, two subsequent calls to paint() must always produce
+    the same output, unless update() was called between them.
+
+    \note Enabling caching for an item does not guarantee that paint()
+    will be invoked only once by the Graphics View framework,
+    even without any explicit call to update(). See the documentation of
+    setCacheMode() for more details.
+
     \sa setCacheMode(), QPen::width(), {Item Coordinates}, ItemUsesExtendedStyleOption
 */