From 645f9eec00b63c076cad488c7ec19a5be9e5dd5e Mon Sep 17 00:00:00 2001
From: Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
Date: Mon, 3 Nov 2014 20:38:01 +0100
Subject: [PATCH] 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>
---
src/widgets/graphicsview/qgraphicsitem.cpp | 22 ++++++++++++++++++++--
1 file changed, 20 insertions(+), 2 deletions(-)
diff --git a/src/widgets/graphicsview/qgraphicsitem.cpp b/src/widgets/graphicsview/qgraphicsitem.cpp
index 76a75dfc350..300e2f492b8 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
*/
--
GitLab