From 645f9eec00b63c076cad488c7ec19a5be9e5dd5e Mon Sep 17 00:00:00 2001 From: Giuseppe D'Angelo Date: Mon, 3 Nov 2014 20:38:01 +0100 Subject: 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 Reviewed-by: Andy Shaw --- 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 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 */ -- cgit v1.2.3