From c6d243df383514f2bf30e178eba087a312191b0f Mon Sep 17 00:00:00 2001 From: Volker Hilsheimer Date: Tue, 21 Jul 2009 10:03:17 +0200 Subject: 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 --- src/gui/image/qimage.cpp | 9 +++--- src/gui/image/qpixmap.cpp | 70 +++++++++++++++++++++++------------------------ 2 files changed, 38 insertions(+), 41 deletions(-) diff --git a/src/gui/image/qimage.cpp b/src/gui/image/qimage.cpp index ad55dcd..7d7dde1 100644 --- a/src/gui/image/qimage.cpp +++ b/src/gui/image/qimage.cpp @@ -612,9 +612,6 @@ bool QImageData::checkForAlphaPixels() const \table \header \o Function \o Description \row - \o setAlphaChannel() - \o Sets the alpha channel of the image. - \row \o setDotsPerMeterX() \o Defines the aspect ratio by setting the number of pixels that fit horizontally in a physical meter. @@ -5587,7 +5584,7 @@ bool QImage::isDetached() const Note that the image will be converted to the Format_ARGB32_Premultiplied format if the function succeeds. - Use one of the composition mods in QPainter::CompositionMode instead. + Use one of the composition modes in QPainter::CompositionMode instead. \warning This function is expensive. @@ -5665,6 +5662,8 @@ void QImage::setAlphaChannel(const QImage &alphaChannel) /*! + \obsolete + Returns the alpha channel of the image as a new grayscale QImage in which each pixel's red, green, and blue values are given the alpha value of the original image. The color depth of the returned image is 8-bit. @@ -5744,7 +5743,7 @@ QImage QImage::alphaChannel() const Returns true if the image has a format that respects the alpha channel, otherwise returns false. - \sa alphaChannel(), {QImage#Image Information}{Image Information} + \sa {QImage#Image Information}{Image Information} */ bool QImage::hasAlphaChannel() const { 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. -- cgit v0.12