src/gui/image/qimage.h

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtGui module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #ifndef QIMAGE_H
  43 #define QIMAGE_H
  44
  45 #include <QtGui/qtransform.h>
  46 #include <QtGui/qpaintdevice.h>
  47 #include <QtGui/qrgb.h>
  48 #include <QtCore/qbytearray.h>
  49 #include <QtCore/qrect.h>
  50 #include <QtCore/qstring.h>
  51
  52 #if QT_DEPRECATED_SINCE(5, 0)
  53 #include <QtCore/qstringlist.h>
  54 #endif
  55
  56 QT_BEGIN_HEADER
  57
  58 QT_BEGIN_NAMESPACE
  59
  60
  61 class QIODevice;
  62 class QStringList;
  63 class QMatrix;
  64 class QTransform;
  65 class QVariant;
  66 template <class T> class QList;
  67 template <class T> class QVector;
  68
  69 struct QImageData;
  70 class QImageDataMisc; // internal
  71 #if QT_DEPRECATED_SINCE(5, 0)
  72 class QImageTextKeyLang {
  73 public:
  74     QT_DEPRECATED QImageTextKeyLang(const char* k, const char* l) : key(k), lang(l) { }
  75     QT_DEPRECATED QImageTextKeyLang() { }
  76
  77     QByteArray key;
  78     QByteArray lang;
  79
  80     bool operator< (const QImageTextKeyLang& other) const
  81         { return key < other.key || (key==other.key && lang < other.lang); }
  82     bool operator== (const QImageTextKeyLang& other) const
  83         { return key==other.key && lang==other.lang; }
  84     inline bool operator!= (const QImageTextKeyLang &other) const
  85         { return !operator==(other); }
  86 private:
  87     friend class QImage;
  88     QImageTextKeyLang(bool /*dummy*/) {}
  89 };
  90 #endif
  91
  92 typedef void (*QImageCleanupFunction)(void*);
  93
  94 class Q_GUI_EXPORT QImage : public QPaintDevice
  95 {
  96 public:
  97     enum InvertMode { InvertRgb, InvertRgba };
  98     enum Format {
  99         Format_Invalid,
 100         Format_Mono,
 101         Format_MonoLSB,
 102         Format_Indexed8,
 103         Format_RGB32,
 104         Format_ARGB32,
 105         Format_ARGB32_Premultiplied,
 106         Format_RGB16,
 107         Format_ARGB8565_Premultiplied,
 108         Format_RGB666,
 109         Format_ARGB6666_Premultiplied,
 110         Format_RGB555,
 111         Format_ARGB8555_Premultiplied,
 112         Format_RGB888,
 113         Format_RGB444,
 114         Format_ARGB4444_Premultiplied,
 115 #if 0
 116         // reserved for future use
 117         Format_RGB15,
 118         Format_Grayscale16,
 119         Format_Grayscale8,
 120         Format_Grayscale4,
 121         Format_Grayscale4LSB,
 122         Format_Grayscale2,
 123         Format_Grayscale2LSB
 124 #endif
 125 #ifndef qdoc
 126         NImageFormats
 127 #endif
 128     };
 129
 130     QImage();
 131     QImage(const QSize &size, Format format);
 132     QImage(int width, int height, Format format);
 133     QImage(uchar *data, int width, int height, Format format, QImageCleanupFunction cleanupFunction = 0, void *cleanupInfo = 0);
 134     QImage(const uchar *data, int width, int height, Format format, QImageCleanupFunction cleanupFunction = 0, void *cleanupInfo = 0);
 135     QImage(uchar *data, int width, int height, int bytesPerLine, Format format, QImageCleanupFunction cleanupFunction = 0, void *cleanupInfo = 0);
 136     QImage(const uchar *data, int width, int height, int bytesPerLine, Format format, QImageCleanupFunction cleanupFunction = 0, void *cleanupInfo = 0);
 137
 138 #ifndef QT_NO_IMAGEFORMAT_XPM
 139     explicit QImage(const char * const xpm[]);
 140 #endif
 141     explicit QImage(const QString &fileName, const char *format = 0);
 142
 143     QImage(const QImage &);
 144     ~QImage();
 145
 146     QImage &operator=(const QImage &);
 147 #ifdef Q_COMPILER_RVALUE_REFS
 148     inline QImage &operator=(QImage &&other)
 149     { qSwap(d, other.d); return *this; }
 150 #endif
 151     inline void swap(QImage &other) { qSwap(d, other.d); }
 152
 153     bool isNull() const;
 154
 155     int devType() const;
 156
 157     bool operator==(const QImage &) const;
 158     bool operator!=(const QImage &) const;
 159     operator QVariant() const;
 160     void detach();
 161     bool isDetached() const;
 162
 163     QImage copy(const QRect &rect = QRect()) const;
 164     inline QImage copy(int x, int y, int w, int h) const
 165         { return copy(QRect(x, y, w, h)); }
 166
 167     Format format() const;
 168
 169     QImage convertToFormat(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) const Q_REQUIRED_RESULT;
 170     QImage convertToFormat(Format f, const QVector<QRgb> &colorTable, Qt::ImageConversionFlags flags = Qt::AutoColor) const Q_REQUIRED_RESULT;
 171
 172     int width() const;
 173     int height() const;
 174     QSize size() const;
 175     QRect rect() const;
 176
 177     int depth() const;
 178     int colorCount() const;
 179     int bitPlaneCount() const;
 180
 181     QRgb color(int i) const;
 182     void setColor(int i, QRgb c);
 183     void setColorCount(int);
 184
 185     bool allGray() const;
 186     bool isGrayscale() const;
 187
 188     uchar *bits();
 189     const uchar *bits() const;
 190     const uchar *constBits() const;
 191
 192     int byteCount() const;
 193
 194     uchar *scanLine(int);
 195     const uchar *scanLine(int) const;
 196     const uchar *constScanLine(int) const;
 197     int bytesPerLine() const;
 198
 199     bool valid(int x, int y) const;
 200     bool valid(const QPoint &pt) const;
 201
 202     int pixelIndex(int x, int y) const;
 203     int pixelIndex(const QPoint &pt) const;
 204
 205     QRgb pixel(int x, int y) const;
 206     QRgb pixel(const QPoint &pt) const;
 207
 208     void setPixel(int x, int y, uint index_or_rgb);
 209     void setPixel(const QPoint &pt, uint index_or_rgb);
 210
 211     QVector<QRgb> colorTable() const;
 212     void setColorTable(const QVector<QRgb> colors);
 213
 214     void fill(uint pixel);
 215     void fill(const QColor &color);
 216     void fill(Qt::GlobalColor color);
 217
 218
 219     bool hasAlphaChannel() const;
 220     void setAlphaChannel(const QImage &alphaChannel);
 221     QImage alphaChannel() const;
 222     QImage createAlphaMask(Qt::ImageConversionFlags flags = Qt::AutoColor) const;
 223 #ifndef QT_NO_IMAGE_HEURISTIC_MASK
 224     QImage createHeuristicMask(bool clipTight = true) const;
 225 #endif
 226     QImage createMaskFromColor(QRgb color, Qt::MaskMode mode = Qt::MaskInColor) const;
 227
 228     inline QImage scaled(int w, int h, Qt::AspectRatioMode aspectMode = Qt::IgnoreAspectRatio,
 229                         Qt::TransformationMode mode = Qt::FastTransformation) const
 230         { return scaled(QSize(w, h), aspectMode, mode); }
 231     QImage scaled(const QSize &s, Qt::AspectRatioMode aspectMode = Qt::IgnoreAspectRatio,
 232                  Qt::TransformationMode mode = Qt::FastTransformation) const;
 233     QImage scaledToWidth(int w, Qt::TransformationMode mode = Qt::FastTransformation) const;
 234     QImage scaledToHeight(int h, Qt::TransformationMode mode = Qt::FastTransformation) const;
 235     QImage transformed(const QMatrix &matrix, Qt::TransformationMode mode = Qt::FastTransformation) const;
 236     static QMatrix trueMatrix(const QMatrix &, int w, int h);
 237     QImage transformed(const QTransform &matrix, Qt::TransformationMode mode = Qt::FastTransformation) const;
 238     static QTransform trueMatrix(const QTransform &, int w, int h);
 239     QImage mirrored(bool horizontally = false, bool vertically = true) const;
 240     QImage rgbSwapped() const;
 241     void invertPixels(InvertMode = InvertRgb);
 242
 243
 244     bool load(QIODevice *device, const char* format);
 245     bool load(const QString &fileName, const char* format=0);
 246     bool loadFromData(const uchar *buf, int len, const char *format = 0);
 247     inline bool loadFromData(const QByteArray &data, const char* aformat=0)
 248         { return loadFromData(reinterpret_cast<const uchar *>(data.constData()), data.size(), aformat); }
 249
 250     bool save(const QString &fileName, const char* format=0, int quality=-1) const;
 251     bool save(QIODevice *device, const char* format=0, int quality=-1) const;
 252
 253     static QImage fromData(const uchar *data, int size, const char *format = 0);
 254     inline static QImage fromData(const QByteArray &data, const char *format = 0)
 255         { return fromData(reinterpret_cast<const uchar *>(data.constData()), data.size(), format); }
 256
 257 #if QT_DEPRECATED_SINCE(5, 0)
 258     QT_DEPRECATED inline int serialNumber() const { return cacheKey() >> 32; }
 259 #endif
 260     qint64 cacheKey() const;
 261
 262     QPaintEngine *paintEngine() const;
 263
 264     // Auxiliary data
 265     int dotsPerMeterX() const;
 266     int dotsPerMeterY() const;
 267     void setDotsPerMeterX(int);
 268     void setDotsPerMeterY(int);
 269     QPoint offset() const;
 270     void setOffset(const QPoint&);
 271
 272     QStringList textKeys() const;
 273     QString text(const QString &key = QString()) const;
 274     void setText(const QString &key, const QString &value);
 275
 276 #if QT_DEPRECATED_SINCE(5, 0)
 277     QT_DEPRECATED inline QString text(const char* key, const char* lang=0) const;
 278     QT_DEPRECATED inline QList<QImageTextKeyLang> textList() const;
 279     QT_DEPRECATED inline QStringList textLanguages() const;
 280     QT_DEPRECATED inline QString text(const QImageTextKeyLang&) const;
 281     QT_DEPRECATED inline void setText(const char* key, const char* lang, const QString&);
 282 #endif
 283
 284 #if QT_DEPRECATED_SINCE(5, 0)
 285     QT_DEPRECATED inline int numColors() const;
 286     QT_DEPRECATED inline void setNumColors(int);
 287     QT_DEPRECATED inline int numBytes() const;
 288 #endif
 289
 290 protected:
 291     virtual int metric(PaintDeviceMetric metric) const;
 292
 293 private:
 294     friend class QWSOnScreenSurface;
 295     QImageData *d;
 296
 297     friend class QRasterPlatformPixmap;
 298     friend class QBlittablePlatformPixmap;
 299     friend class QPixmapCacheEntry;
 300
 301 public:
 302     typedef QImageData * DataPtr;
 303     inline DataPtr &data_ptr() { return d; }
 304 };
 305
 306 Q_DECLARE_SHARED(QImage)
 307 Q_DECLARE_TYPEINFO(QImage, Q_MOVABLE_TYPE);
 308
 309 // Inline functions...
 310
 311 inline bool QImage::valid(const QPoint &pt) const { return valid(pt.x(), pt.y()); }
 312 inline int QImage::pixelIndex(const QPoint &pt) const { return pixelIndex(pt.x(), pt.y());}
 313 inline QRgb QImage::pixel(const QPoint &pt) const { return pixel(pt.x(), pt.y()); }
 314 inline void QImage::setPixel(const QPoint &pt, uint index_or_rgb) { setPixel(pt.x(), pt.y(), index_or_rgb); }
 315
 316 #if QT_DEPRECATED_SINCE(5, 0)
 317
 318 #if defined(Q_CC_GNU) && !defined(Q_CC_INTEL) && (__GNUC__ * 100 + __GNUC_MINOR__ >= 406)
 319 # pragma GCC diagnostic push
 320 # pragma GCC diagnostic ignored "-Wdeprecated-declarations"
 321 #elif defined(Q_CC_MSVC)
 322 # pragma warning(disable: 4996)
 323 #endif
 324
 325 inline QString QImage::text(const char* key, const char* lang) const
 326 {
 327     if (!d)
 328         return QString();
 329     QString k = QString::fromAscii(key);
 330     if (lang && *lang)
 331         k += QLatin1Char('/') + QString::fromAscii(lang);
 332     return text(k);
 333 }
 334
 335 inline QList<QImageTextKeyLang> QImage::textList() const
 336 {
 337     QList<QImageTextKeyLang> imageTextKeys;
 338     if (!d)
 339         return imageTextKeys;
 340     QStringList keys = textKeys();
 341     for (int i = 0; i < keys.size(); ++i) {
 342         int index = keys.at(i).indexOf(QLatin1Char('/'));
 343         if (index > 0) {
 344             QImageTextKeyLang tkl(true);
 345             tkl.key = keys.at(i).left(index).toAscii();
 346             tkl.lang = keys.at(i).mid(index+1).toAscii();
 347             imageTextKeys += tkl;
 348         }
 349     }
 350
 351     return imageTextKeys;
 352 }
 353
 354 inline QStringList QImage::textLanguages() const
 355 {
 356     if (!d)
 357         return QStringList();
 358     QStringList keys = textKeys();
 359     QStringList languages;
 360     for (int i = 0; i < keys.size(); ++i) {
 361         int index = keys.at(i).indexOf(QLatin1Char('/'));
 362         if (index > 0)
 363             languages += keys.at(i).mid(index+1);
 364     }
 365
 366     return languages;
 367 }
 368
 369 inline QString QImage::text(const QImageTextKeyLang&kl) const
 370 {
 371     if (!d)
 372         return QString();
 373     QString k = QString::fromAscii(kl.key.constData());
 374     if (!kl.lang.isEmpty())
 375         k += QLatin1Char('/') + QString::fromAscii(kl.lang.constData());
 376     return text(k);
 377 }
 378
 379 inline void QImage::setText(const char* key, const char* lang, const QString &s)
 380 {
 381     if (!d)
 382         return;
 383     detach();
 384
 385     // In case detach() ran out of memory
 386     if (!d)
 387         return;
 388
 389     QString k = QString::fromAscii(key);
 390     if (lang && *lang)
 391         k += QLatin1Char('/') + QString::fromAscii(lang);
 392     setText(k, s);
 393 }
 394
 395 #if defined(Q_CC_GNU) && !defined(Q_CC_INTEL) && (__GNUC__ * 100 + __GNUC_MINOR__ >= 406)
 396 # pragma GCC diagnostic pop
 397 #elif defined(Q_CC_MSVC)
 398 # pragma warning(default: 4996)
 399 #endif
 400
 401 inline int QImage::numColors() const
 402 {
 403     return colorCount();
 404 }
 405
 406 inline void QImage::setNumColors(int n)
 407 {
 408     setColorCount(n);
 409 }
 410
 411 inline int QImage::numBytes() const
 412 {
 413     return byteCount();
 414 }
 415 #endif
 416
 417 // QImage stream functions
 418
 419 #if !defined(QT_NO_DATASTREAM)
 420 Q_GUI_EXPORT QDataStream &operator<<(QDataStream &, const QImage &);
 421 Q_GUI_EXPORT QDataStream &operator>>(QDataStream &, QImage &);
 422 #endif
 423
 424 #ifndef QT_NO_DEBUG_STREAM
 425 Q_GUI_EXPORT QDebug operator<<(QDebug, const QImage &);
 426 #endif
 427
 428
 429 QT_END_NAMESPACE
 430
 431 QT_END_HEADER
 432
 433 #endif // QIMAGE_H