Adds a few \warnings to the docs on do-not-use-for-performance-reasons

Reviewed-by: Trond

4 files changed, 43 insertions, 5 deletions

diff --git a/src/gui/graphicsview/qgraphicsproxywidget.cpp b/src/gui/graphicsview/qgraphicsproxywidget.cpp
index 1d2721b..e660879 100644
--- a/src/gui/graphicsview/qgraphicsproxywidget.cpp
+++ b/src/gui/graphicsview/qgraphicsproxywidget.cpp
@@ -177,6 +177,10 @@ QT_BEGIN_NAMESPACE
     while the widget is embedded. In this state, the widget may differ slightly
     in behavior from when it is not embedded.
 
+    \warning This class is provided for convenience when bridging
+    QWidgets and QGraphicsItems, it should not be used for
+    high-performance scenarios.
+
     \sa QGraphicsScene::addWidget(), QGraphicsWidget
 */
 
@@ -1033,7 +1037,7 @@ void QGraphicsProxyWidget::dragMoveEvent(QGraphicsSceneDragDropEvent *event)
         if (receiver != d->dragDropWidget) {
             // Try to enter before we leave
             QDragEnterEvent dragEnter(receiverPos, event->possibleActions(), event->mimeData(), event->buttons(), event->modifiers());
-            dragEnter.setDropAction(event->proposedAction());            
+            dragEnter.setDropAction(event->proposedAction());
             QApplication::sendEvent(receiver, &dragEnter);
             event->setAccepted(dragEnter.isAccepted());
             event->setDropAction(dragEnter.dropAction());
@@ -1431,7 +1435,7 @@ int QGraphicsProxyWidget::type() const
 
   Creates a proxy widget for the given \a child of the widget
   contained in this proxy.
-  
+
   This function makes it possible to aquire proxies for
   non top-level widgets. For instance, you can embed a dialog,
   and then transform only one of its widgets.
diff --git a/src/gui/image/qimage.cpp b/src/gui/image/qimage.cpp
index dc236e4..6945ef8 100644
--- a/src/gui/image/qimage.cpp
+++ b/src/gui/image/qimage.cpp
@@ -114,7 +114,7 @@ Q_GUI_EXPORT _qt_image_cleanup_hook qt_image_cleanup_hook = 0;
 typedef void (*_qt_image_cleanup_hook_64)(qint64);
 Q_GUI_EXPORT _qt_image_cleanup_hook_64 qt_image_cleanup_hook_64 = 0;
 
-static QImage rotated90(const QImage &src);
+static QImage rotated90(const QImage &src);=
 static QImage rotated180(const QImage &src);
 static QImage rotated270(const QImage &src);
 
@@ -3607,6 +3607,9 @@ int QImage::pixelIndex(int x, int y) const
 
     If the \a position is not valid, the results are undefined.
 
+    \warning This function is expensive when used for massive pixel
+    manipulations.
+
     \sa setPixel(), valid(), {QImage#Pixel Manipulation}{Pixel
     Manipulation}
 */
@@ -5581,6 +5584,8 @@ bool QImage::isDetached() const
 
     Use one of the composition mods in QPainter::CompositionMode instead.
 
+    \warning This function is expensive.
+
     \sa alphaChannel(), {QImage#Image Transformations}{Image
     Transformations}, {QImage#Image Formats}{Image Formats}
 */
@@ -5663,6 +5668,11 @@ void QImage::setAlphaChannel(const QImage &alphaChannel)
     \l{QPixmap::}{alphaChannel()}, which works in the same way as
     this function on QPixmaps.
 
+    Most usecases for this function can be replaced with QPainter and
+    using composition modes.
+
+    \warning This is an expensive function.
+
     \sa setAlphaChannel(), hasAlphaChannel(),
     {QPixmap#Pixmap Information}{Pixmap},
     {QImage#Image Transformations}{Image Transformations}
diff --git a/src/gui/image/qpixmap.cpp b/src/gui/image/qpixmap.cpp
index 8684a1b..efb8260 100644
--- a/src/gui/image/qpixmap.cpp
+++ b/src/gui/image/qpixmap.cpp
@@ -674,7 +674,7 @@ void QPixmap::resize_helper(const QSize &s)
     pixels black. The effect of this function is undefined when the pixmap is
     being painted on.
 
-    This is potentially an expensive operation.
+    \warning This is potentially an expensive operation.
 
     \sa mask(), {QPixmap#Pixmap Transformations}{Pixmap Transformations},
     QBitmap
@@ -1380,6 +1380,12 @@ void QPixmap::deref()
     If the given \a size is empty, this function returns a null
     pixmap.
 
+
+    In some cases it can be more beneficial to draw the pixmap to a
+    painter with a scale set rather than scaling the pixmap. This is
+    the case when the painter is for instance based on OpenGL or when
+    the scale factor changes rapidly.
+
     \sa isNull(), {QPixmap#Pixmap Transformations}{Pixmap
     Transformations}
 
@@ -1751,6 +1757,10 @@ int QPixmap::metric(PaintDeviceMetric metric) const
     The effect of this function is undefined when the pixmap is being
     painted on.
 
+    \warning This is potentially an expensive operation. Most usecases
+    for this function are covered by QPainter and compositionModes
+    which will normally execute faster.
+
     \sa alphaChannel(), {QPixmap#Pixmap Transformations}{Pixmap
     Transformations}
  */
@@ -1793,6 +1803,9 @@ void QPixmap::setAlphaChannel(const QPixmap &alphaChannel)
 
     \image alphachannelimage.png The pixmap and channelImage QPixmaps
 
+    \warning This is an expensive operation. The alpha channel of the
+    pixmap is extracted dynamically from the pixeldata.
+
     \sa setAlphaChannel(), {QPixmap#Pixmap Information}{Pixmap
     Information}
 */
@@ -1814,7 +1827,8 @@ QPaintEngine *QPixmap::paintEngine() const
 
     Extracts a bitmap mask from the pixmap's alphachannel.
 
-    This is potentially an expensive operation.
+    \warning This is potentially an expensive operation. The mask of
+    the pixmap is extracted dynamically from the pixeldata.
 
     \sa setMask(), {QPixmap#Pixmap Information}{Pixmap Information}
 */
diff --git a/src/gui/painting/qpainter.cpp b/src/gui/painting/qpainter.cpp
index b2f0ac4..2beb8c2 100644
--- a/src/gui/painting/qpainter.cpp
+++ b/src/gui/painting/qpainter.cpp
@@ -2371,6 +2371,11 @@ void QPainter::setClipping(bool enable)
     Returns the currently set clip region. Note that the clip region
     is given in logical coordinates.
 
+    \warning QPainter does not store the combined clip explicitly as
+    this is handled by the underlying QPaintEngine, so the path is
+    recreated on demand and transformed to the current logical
+    coordinate system. This is potentially an expensive operation.
+
     \sa setClipRegion(), clipPath(), setClipping()
 */
 
@@ -2486,6 +2491,11 @@ extern QPainterPath qt_regionToPath(const QRegion &region);
     Returns the currently clip as a path. Note that the clip path is
     given in logical coordinates.
 
+    \warning QPainter does not store the combined clip explicitly as
+    this is handled by the underlying QPaintEngine, so the path is
+    recreated on demand and transformed to the current logical
+    coordinate system. This is potentially an expensive operation.
+
     \sa setClipPath(), clipRegion(), setClipping()
 */
 QPainterPath QPainter::clipPath() const