Doc: mark QImage/QPixmap alphaChannel and setAlphaChannel as obsolete.

They are expensive - which is why QImage::setALphaChannel had been
obsoleted in Qt 4.5.

Reviewed-by: Gunnar

1 files changed, 34 insertions, 36 deletions

diff --git a/src/gui/image/qpixmap.cpp b/src/gui/image/qpixmap.cpp
index 72fdec0..3e5c9b7 100644
--- a/src/gui/image/qpixmap.cpp
+++ b/src/gui/image/qpixmap.cpp
@@ -1572,24 +1572,24 @@ QPixmap QPixmap::transformed(const QMatrix &matrix, Qt::TransformationMode mode)
     designed and optimized for showing images on screen. QBitmap is
     only a convenience class that inherits QPixmap, ensuring a depth
     of 1. The isQBitmap() function returns true if a QPixmap object is
-    really a bitmap, otherwise returns false. Finally, the QPicture class is a
-    paint device that records and replays QPainter commands.
+    really a bitmap, otherwise returns false. Finally, the QPicture class
+    is a paint device that records and replays QPainter commands.
 
     A QPixmap can easily be displayed on the screen using QLabel or
     one of QAbstractButton's subclasses (such as QPushButton and
     QToolButton). QLabel has a pixmap property, whereas
-    QAbstractButton has an icon property. And because QPixmap is a
-    QPaintDevice subclass, QPainter can be used to draw directly onto
-    pixmaps.
+    QAbstractButton has an icon property.
 
     In addition to the ordinary constructors, a QPixmap can be
     constructed using the static grabWidget() and grabWindow()
     functions which creates a QPixmap and paints the given widget, or
-    window, in it.
+    window, into it.
+
+    QPixmap objects can be passed around by value since the QPixmap
+    class uses implicit data sharing. For more information, see the \l
+    {Implicit Data Sharing} documentation. QPixmap objects can also be
+    streamed.
 
-    Note that the pixel data in a pixmap is internal and is managed by
-    the underlying window system. Pixels can only be accessed through
-    QPainter functions or by converting the QPixmap to a QImage.
     Depending on the system, QPixmap is stored using a RGB32 or a
     premultiplied alpha format. If the image has an alpha channel, and
     if the system allows, the preferred format is premultiplied alpha.
@@ -1600,6 +1600,13 @@ QPixmap QPixmap::transformed(const QMatrix &matrix, Qt::TransformationMode mode)
     QPixmap are stored on the client side and don't use any GDI
     resources).
 
+    Note that the pixel data in a pixmap is internal and is managed by
+    the underlying window system. Because QPixmap is a QPaintDevice
+    subclass, QPainter can be used to draw directly onto pixmaps.
+    Pixels can only be accessed through QPainter functions or by
+    converting the QPixmap to a QImage. However, the fill() function
+    is available for initializing the entire pixmap with a given color.
+
     There are functions to convert between QImage and
     QPixmap. Typically, the QImage class is used to load an image
     file, optionally manipulating the image data, before the QImage
@@ -1614,11 +1621,6 @@ QPixmap QPixmap::transformed(const QMatrix &matrix, Qt::TransformationMode mode)
     there are several functions that enables transformation of the
     pixmap.
 
-    QPixmap objects can be passed around by value since the QPixmap
-    class uses implicit data sharing. For more information, see the \l
-    {Implicit Data Sharing} documentation. QPixmap objects can also be
-    streamed.
-
     \tableofcontents
 
     \section1 Reading and Writing Image Files
@@ -1675,12 +1677,15 @@ QPixmap QPixmap::transformed(const QMatrix &matrix, Qt::TransformationMode mode)
     The hasAlphaChannel() returns true if the pixmap has a format that
     respects the alpha channel, otherwise returns false, while the
     hasAlpha() function returns true if the pixmap has an alpha
-    channel \e or a mask (otherwise false).
+    channel \e or a mask (otherwise false). The mask() function returns
+    the mask as a QBitmap object, which can be set using setMask().
 
-    The alphaChannel() function returns the alpha channel as a new
-    QPixmap object, while the mask() function returns the mask as a
-    QBitmap object. The alpha channel and mask can be set using the
-    setAlphaChannel() and setMask() functions, respectively.
+    The createHeuristicMask() function creates and returns a 1-bpp
+    heuristic mask (i.e. a QBitmap) for this pixmap. It works by
+    selecting a color from one of the corners and then chipping away
+    pixels of that color, starting at all the edges. The
+    createMaskFromColor() function creates and returns a mask (i.e. a
+    QBitmap) for the pixmap based on a given color.
 
     \row
     \o Low-level information
@@ -1718,14 +1723,7 @@ QPixmap QPixmap::transformed(const QMatrix &matrix, Qt::TransformationMode mode)
     \section1 Pixmap Transformations
 
     QPixmap supports a number of functions for creating a new pixmap
-    that is a transformed version of the original: The
-    createHeuristicMask() function creates and returns a 1-bpp
-    heuristic mask (i.e. a QBitmap) for this pixmap. It works by
-    selecting a color from one of the corners and then chipping away
-    pixels of that color, starting at all the edges. The
-    createMaskFromColor() function creates and returns a mask (i.e. a
-    QBitmap) for the pixmap based on a given color.
-
+    that is a transformed version of the original:
 
     The scaled(), scaledToWidth() and scaledToHeight() functions
     return scaled copies of the pixmap, while the copy() function
@@ -1740,11 +1738,6 @@ QPixmap QPixmap::transformed(const QMatrix &matrix, Qt::TransformationMode mode)
     function returns the actual matrix used for transforming the
     pixmap.
 
-    There are also functions for changing attributes of a pixmap.
-    in-place: The fill() function fills the entire image with the
-    given color, the setMask() function sets a mask bitmap, and the
-    setAlphaChannel() function sets the pixmap's alpha channel.
-
     \sa QBitmap, QImage, QImageReader, QImageWriter
 */
 
@@ -1763,7 +1756,7 @@ QPixmap QPixmap::transformed(const QMatrix &matrix, Qt::TransformationMode mode)
     Returns true if this pixmap has an alpha channel, \e or has a
     mask, otherwise returns false.
 
-    \sa hasAlphaChannel(), alphaChannel(), mask()
+    \sa hasAlphaChannel(), mask()
 */
 bool QPixmap::hasAlpha() const
 {
@@ -1774,7 +1767,7 @@ bool QPixmap::hasAlpha() const
     Returns true if the pixmap has a format that respects the alpha
     channel, otherwise returns false.
 
-    \sa alphaChannel(), hasAlpha()
+    \sa hasAlpha()
 */
 bool QPixmap::hasAlphaChannel() const
 {
@@ -1791,6 +1784,7 @@ int QPixmap::metric(PaintDeviceMetric metric) const
 
 /*!
     \fn void QPixmap::setAlphaChannel(const QPixmap &alphaChannel)
+    \obsolete
 
     Sets the alpha channel of this pixmap to the given \a alphaChannel
     by converting the \a alphaChannel into 32 bit and using the
@@ -1828,6 +1822,8 @@ void QPixmap::setAlphaChannel(const QPixmap &alphaChannel)
 }
 
 /*!
+    \obsolete
+
     Returns the alpha channel of the pixmap as a new grayscale QPixmap in which
     each pixel's red, green, and blue values are given the alpha value of the
     original pixmap. The color depth of the returned pixmap is the system depth
@@ -1846,7 +1842,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.
+    pixmap is extracted dynamically from the pixeldata. Most usecases of this
+    function are covered by QPainter and compositionModes which will normally
+    execute faster.
 
     \sa setAlphaChannel(), {QPixmap#Pixmap Information}{Pixmap
     Information}
@@ -1867,7 +1865,7 @@ QPaintEngine *QPixmap::paintEngine() const
 /*!
     \fn QBitmap QPixmap::mask() const
 
-    Extracts a bitmap mask from the pixmap's alphachannel.
+    Extracts a bitmap mask from the pixmap's alpha channel.
 
     \warning This is potentially an expensive operation. The mask of
     the pixmap is extracted dynamically from the pixeldata.