Qt 4.8
qimage.h
Go to the documentation of this file.
1 /****************************************************************************
2 **
3 ** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
5 **
6 ** This file is part of the QtGui module of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and Digia. For licensing terms and
14 ** conditions see http://qt.digia.com/licensing. For further information
15 ** use the contact form at http://qt.digia.com/contact-us.
16 **
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 2.1 as published by the Free Software
20 ** Foundation and appearing in the file LICENSE.LGPL included in the
21 ** packaging of this file. Please review the following information to
22 ** ensure the GNU Lesser General Public License version 2.1 requirements
23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
24 **
25 ** In addition, as a special exception, Digia gives you certain additional
26 ** rights. These rights are described in the Digia Qt LGPL Exception
27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
28 **
29 ** GNU General Public License Usage
30 ** Alternatively, this file may be used under the terms of the GNU
31 ** General Public License version 3.0 as published by the Free Software
32 ** Foundation and appearing in the file LICENSE.GPL included in the
33 ** packaging of this file. Please review the following information to
34 ** ensure the GNU General Public License version 3.0 requirements will be
35 ** met: http://www.gnu.org/copyleft/gpl.html.
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 
53 
55 
56 QT_MODULE(Gui)
57 
58 class QIODevice;
59 class QStringList;
60 class QMatrix;
61 class QTransform;
62 class QVariant;
63 template <class T> class QList;
64 template <class T> class QVector;
65 
66 struct QImageData;
67 class QImageDataMisc; // internal
68 #ifndef QT_NO_IMAGE_TEXT
70 public:
71  QImageTextKeyLang(const char* k, const char* l) : key(k), lang(l) { }
73 
76 
77  bool operator< (const QImageTextKeyLang& other) const
78  { return key < other.key || (key==other.key && lang < other.lang); }
79  bool operator== (const QImageTextKeyLang& other) const
80  { return key==other.key && lang==other.lang; }
81  inline bool operator!= (const QImageTextKeyLang &other) const
82  { return !operator==(other); }
83 };
84 #endif //QT_NO_IMAGE_TEXT
85 
86 
88 {
89 public:
90  enum InvertMode { InvertRgb, InvertRgba };
91  enum Format {
108 #if 0
109  // reserved for future use
110  Format_RGB15,
111  Format_Grayscale16,
112  Format_Grayscale8,
113  Format_Grayscale4,
114  Format_Grayscale4LSB,
115  Format_Grayscale2,
116  Format_Grayscale2LSB
117 #endif
118 #ifndef qdoc
119  NImageFormats
120 #endif
121  };
122 
123  QImage();
124  QImage(const QSize &size, Format format);
125  QImage(int width, int height, Format format);
126  QImage(uchar *data, int width, int height, Format format);
127  QImage(const uchar *data, int width, int height, Format format);
128  QImage(uchar *data, int width, int height, int bytesPerLine, Format format);
129  QImage(const uchar *data, int width, int height, int bytesPerLine, Format format);
130 
131 #ifndef QT_NO_IMAGEFORMAT_XPM
132  explicit QImage(const char * const xpm[]);
133 #endif
134  explicit QImage(const QString &fileName, const char *format = 0);
135 #ifndef QT_NO_CAST_FROM_ASCII
136  explicit QImage(const char *fileName, const char *format = 0);
137 #endif
138 
139  QImage(const QImage &);
140  ~QImage();
141 
142  QImage &operator=(const QImage &);
143 #ifdef Q_COMPILER_RVALUE_REFS
144  inline QImage &operator=(QImage &&other)
145  { qSwap(d, other.d); return *this; }
146 #endif
147  inline void swap(QImage &other) { qSwap(d, other.d); }
148 
149  bool isNull() const;
150 
151  int devType() const;
152 
153  bool operator==(const QImage &) const;
154  bool operator!=(const QImage &) const;
155  operator QVariant() const;
156  void detach();
157  bool isDetached() const;
158 
159  QImage copy(const QRect &rect = QRect()) const;
160  inline QImage copy(int x, int y, int w, int h) const
161  { return copy(QRect(x, y, w, h)); }
162 
163  Format format() const;
164 
165  QImage convertToFormat(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) const Q_REQUIRED_RESULT;
166  QImage convertToFormat(Format f, const QVector<QRgb> &colorTable, Qt::ImageConversionFlags flags = Qt::AutoColor) const Q_REQUIRED_RESULT;
167 
168  int width() const;
169  int height() const;
170  QSize size() const;
171  QRect rect() const;
172 
173  int depth() const;
174 #ifdef QT_DEPRECATED
175  QT_DEPRECATED int numColors() const;
176 #endif
177  int colorCount() const;
178  int bitPlaneCount() const;
179 
180  QRgb color(int i) const;
181  void setColor(int i, QRgb c);
182 #ifdef QT_DEPRECATED
183  QT_DEPRECATED void setNumColors(int);
184 #endif
185  void setColorCount(int);
186 
187  bool allGray() const;
188  bool isGrayscale() const;
189 
190  uchar *bits();
191  const uchar *bits() const;
192  const uchar *constBits() const;
193 #ifdef QT_DEPRECATED
194  QT_DEPRECATED int numBytes() const;
195 #endif
196  int byteCount() const;
197 
198  uchar *scanLine(int);
199  const uchar *scanLine(int) const;
200  const uchar *constScanLine(int) const;
201  int bytesPerLine() const;
202 
203  bool valid(int x, int y) const;
204  bool valid(const QPoint &pt) const;
205 
206  int pixelIndex(int x, int y) const;
207  int pixelIndex(const QPoint &pt) const;
208 
209  QRgb pixel(int x, int y) const;
210  QRgb pixel(const QPoint &pt) const;
211 
212  void setPixel(int x, int y, uint index_or_rgb);
213  void setPixel(const QPoint &pt, uint index_or_rgb);
214 
215  QVector<QRgb> colorTable() const;
216  void setColorTable(const QVector<QRgb> colors);
217 
218  void fill(uint pixel);
219  void fill(const QColor &color);
220  void fill(Qt::GlobalColor color);
221 
222 
223  bool hasAlphaChannel() const;
224  void setAlphaChannel(const QImage &alphaChannel);
225  QImage alphaChannel() const;
226  QImage createAlphaMask(Qt::ImageConversionFlags flags = Qt::AutoColor) const;
227 #ifndef QT_NO_IMAGE_HEURISTIC_MASK
228  QImage createHeuristicMask(bool clipTight = true) const;
229 #endif
230  QImage createMaskFromColor(QRgb color, Qt::MaskMode mode = Qt::MaskInColor) const;
231 
232  inline QImage scaled(int w, int h, Qt::AspectRatioMode aspectMode = Qt::IgnoreAspectRatio,
234  { return scaled(QSize(w, h), aspectMode, mode); }
235  QImage scaled(const QSize &s, Qt::AspectRatioMode aspectMode = Qt::IgnoreAspectRatio,
237  QImage scaledToWidth(int w, Qt::TransformationMode mode = Qt::FastTransformation) const;
238  QImage scaledToHeight(int h, Qt::TransformationMode mode = Qt::FastTransformation) const;
239  QImage transformed(const QMatrix &matrix, Qt::TransformationMode mode = Qt::FastTransformation) const;
240  static QMatrix trueMatrix(const QMatrix &, int w, int h);
241  QImage transformed(const QTransform &matrix, Qt::TransformationMode mode = Qt::FastTransformation) const;
242  static QTransform trueMatrix(const QTransform &, int w, int h);
243  QImage mirrored(bool horizontally = false, bool vertically = true) const;
244  QImage rgbSwapped() const;
245  void invertPixels(InvertMode = InvertRgb);
246 
247 
248  bool load(QIODevice *device, const char* format);
249  bool load(const QString &fileName, const char* format=0);
250  bool loadFromData(const uchar *buf, int len, const char *format = 0);
251  inline bool loadFromData(const QByteArray &data, const char* aformat=0)
252  { return loadFromData(reinterpret_cast<const uchar *>(data.constData()), data.size(), aformat); }
253 
254  bool save(const QString &fileName, const char* format=0, int quality=-1) const;
255  bool save(QIODevice *device, const char* format=0, int quality=-1) const;
256 
257  static QImage fromData(const uchar *data, int size, const char *format = 0);
258  inline static QImage fromData(const QByteArray &data, const char *format = 0)
259  { return fromData(reinterpret_cast<const uchar *>(data.constData()), data.size(), format); }
260 
261  int serialNumber() const;
262  qint64 cacheKey() const;
263 
264  QPaintEngine *paintEngine() const;
265 
266  // Auxiliary data
267  int dotsPerMeterX() const;
268  int dotsPerMeterY() const;
269  void setDotsPerMeterX(int);
270  void setDotsPerMeterY(int);
271  QPoint offset() const;
272  void setOffset(const QPoint&);
273 #ifndef QT_NO_IMAGE_TEXT
274  QStringList textKeys() const;
275  QString text(const QString &key = QString()) const;
276  void setText(const QString &key, const QString &value);
277 
278 #ifdef QT_DEPRECATED
279  QT_DEPRECATED QString text(const char* key, const char* lang=0) const;
280  QT_DEPRECATED QList<QImageTextKeyLang> textList() const;
281  QT_DEPRECATED QStringList textLanguages() const;
283  QT_DEPRECATED void setText(const char* key, const char* lang, const QString&);
284 #endif
285 #endif
286 
287 #ifdef QT3_SUPPORT
288  enum Endian { BigEndian, LittleEndian, IgnoreEndian };
289  QT3_SUPPORT_CONSTRUCTOR QImage(int width, int height, int depth, int numColors=0, Endian bitOrder=IgnoreEndian);
290  QT3_SUPPORT_CONSTRUCTOR QImage(const QSize&, int depth, int numColors=0, Endian bitOrder=IgnoreEndian);
291  QT3_SUPPORT_CONSTRUCTOR QImage(uchar *data, int w, int h, int depth, const QRgb *colortable, int numColors, Endian bitOrder);
292 #ifdef Q_WS_QWS
293  QT3_SUPPORT_CONSTRUCTOR QImage(uchar *data, int w, int h, int depth, int pbl, const QRgb *colortable, int numColors, Endian bitOrder);
294 #endif
295  inline QT3_SUPPORT Endian bitOrder() const {
296  Format f = format();
297  return f == Format_Mono ? BigEndian : (f == Format_MonoLSB ? LittleEndian : IgnoreEndian);
298  }
299  QT3_SUPPORT QImage convertDepth(int, Qt::ImageConversionFlags flags = Qt::AutoColor) const;
300  QT3_SUPPORT QImage convertDepthWithPalette(int, QRgb* p, int pc, Qt::ImageConversionFlags flags = Qt::AutoColor) const;
301  QT3_SUPPORT QImage convertBitOrder(Endian) const;
302  QT3_SUPPORT bool hasAlphaBuffer() const;
303  QT3_SUPPORT void setAlphaBuffer(bool);
304  QT3_SUPPORT uchar **jumpTable();
305  QT3_SUPPORT const uchar * const *jumpTable() const;
306  inline QT3_SUPPORT void reset() { *this = QImage(); }
307  static inline QT3_SUPPORT Endian systemByteOrder()
308  { return QSysInfo::ByteOrder == QSysInfo::BigEndian ? BigEndian : LittleEndian; }
309  inline QT3_SUPPORT QImage swapRGB() const { return rgbSwapped(); }
310  inline QT3_SUPPORT QImage mirror(bool horizontally = false, bool vertically = true) const
311  { return mirrored(horizontally, vertically); }
312  QT3_SUPPORT bool create(const QSize&, int depth, int numColors=0, Endian bitOrder=IgnoreEndian);
313  QT3_SUPPORT bool create(int width, int height, int depth, int numColors=0, Endian bitOrder=IgnoreEndian);
314  inline QT3_SUPPORT QImage xForm(const QMatrix &matrix) const { return transformed(QTransform(matrix)); }
315  inline QT3_SUPPORT QImage smoothScale(int w, int h, Qt::AspectRatioMode mode = Qt::IgnoreAspectRatio) const
316  { return scaled(QSize(w, h), mode, Qt::SmoothTransformation); }
317  inline QImage QT3_SUPPORT smoothScale(const QSize &s, Qt::AspectRatioMode mode = Qt::IgnoreAspectRatio) const
318  { return scaled(s, mode, Qt::SmoothTransformation); }
319  inline QT3_SUPPORT QImage scaleWidth(int w) const { return scaledToWidth(w); }
320  inline QT3_SUPPORT QImage scaleHeight(int h) const { return scaledToHeight(h); }
321  inline QT3_SUPPORT void invertPixels(bool invertAlpha) { invertAlpha ? invertPixels(InvertRgba) : invertPixels(InvertRgb); }
322  inline QT3_SUPPORT QImage copy(int x, int y, int w, int h, Qt::ImageConversionFlags) const
323  { return copy(QRect(x, y, w, h)); }
324  inline QT3_SUPPORT QImage copy(const QRect &rect, Qt::ImageConversionFlags) const
325  { return copy(rect); }
326  static QT3_SUPPORT Endian systemBitOrder();
327  inline QT3_SUPPORT_CONSTRUCTOR QImage(const QByteArray &data)
328  { d = 0; *this = QImage::fromData(data); }
329 #endif
330 
331 protected:
332  virtual int metric(PaintDeviceMetric metric) const;
333 
334 private:
335  friend class QWSOnScreenSurface;
337 
338  friend class QRasterPixmapData;
339  friend class QBlittablePixmapData;
340  friend class QPixmapCacheEntry;
341  friend Q_GUI_EXPORT qint64 qt_image_id(const QImage &image);
342  friend const QVector<QRgb> *qt_image_colortable(const QImage &image);
343 
344 public:
345  typedef QImageData * DataPtr;
346  inline DataPtr &data_ptr() { return d; }
347 };
348 
351 
352 // Inline functions...
353 
354 Q_GUI_EXPORT_INLINE bool QImage::valid(const QPoint &pt) const { return valid(pt.x(), pt.y()); }
355 Q_GUI_EXPORT_INLINE int QImage::pixelIndex(const QPoint &pt) const { return pixelIndex(pt.x(), pt.y());}
356 Q_GUI_EXPORT_INLINE QRgb QImage::pixel(const QPoint &pt) const { return pixel(pt.x(), pt.y()); }
357 Q_GUI_EXPORT_INLINE void QImage::setPixel(const QPoint &pt, uint index_or_rgb) { setPixel(pt.x(), pt.y(), index_or_rgb); }
358 
359 // QImage stream functions
360 
361 #if !defined(QT_NO_DATASTREAM)
364 #endif
365 
366 #ifdef QT3_SUPPORT
367 Q_GUI_EXPORT QT3_SUPPORT void bitBlt(QImage* dst, int dx, int dy, const QImage* src,
368  int sx=0, int sy=0, int sw=-1, int sh=-1, Qt::ImageConversionFlags flags = Qt::AutoColor);
369 #endif
370 
372 
374 
375 #endif // QIMAGE_H
The QVariant class acts like a union for the most common Qt data types.
Definition: qvariant.h:92
The QColor class provides colors based on RGB, HSV or CMYK values.
Definition: qcolor.h:67
double d
Definition: qnumeric_p.h:62
Format
The following image formats are available in Qt.
Definition: qimage.h:91
Q_GUI_EXPORT QDataStream & operator<<(QDataStream &, const QImage &)
Definition: qimage.cpp:5406
unsigned int QRgb
Definition: qrgb.h:53
unsigned char c[8]
Definition: qnumeric_p.h:62
#define QT_END_NAMESPACE
This macro expands to.
Definition: qglobal.h:90
#define QT_MODULE(x)
Definition: qglobal.h:2783
#define QT_BEGIN_HEADER
Definition: qglobal.h:136
The QMatrix class specifies 2D transformations of a coordinate system.
Definition: qmatrix.h:61
MaskMode
Definition: qnamespace.h:1490
QImage copy(int x, int y, int w, int h) const
The returned image is copied from the position (x, y) in this image, and will always have the given w...
Definition: qimage.h:160
#define Q_GUI_EXPORT
Definition: qglobal.h:1450
int height() const
Definition: qpaintdevice.h:92
The QByteArray class provides an array of bytes.
Definition: qbytearray.h:135
static Expression::Ptr create(Expression *const expr, const YYLTYPE &sourceLocator, const ParserContext *const parseInfo)
Q_CORE_EXPORT QTextStream & reset(QTextStream &s)
QImageTextKeyLang(const char *k, const char *l)
Definition: qimage.h:71
InvertMode
This enum type is used to describe how pixel values should be inverted in the invertPixels() function...
Definition: qimage.h:90
Q_GUI_EXPORT QDataStream & operator>>(QDataStream &, QImage &)
Definition: qimage.cpp:5435
bool operator!=(QBool b1, bool b2)
Definition: qglobal.h:2026
The QString class provides a Unicode character string.
Definition: qstring.h:83
QImageData * d
Definition: qimage.h:336
The QVector class is a template class that provides a dynamic array.
Definition: qdatastream.h:64
QRgb pixel(int x, int y) const
Returns the color of the pixel at coordinates (x, y).
Definition: qimage.cpp:4240
bool operator<(int priority, const QPair< QRunnable *, int > &p)
Definition: qthreadpool.cpp:50
virtual int devType() const
Definition: qpaintdevice.h:167
GlobalColor
Definition: qnamespace.h:104
int colorCount() const
Definition: qpaintdevice.h:102
int pixelIndex(int x, int y) const
Returns the pixel index at (x, y).
Definition: qimage.cpp:4194
#define Q_DECLARE_SHARED(TYPE)
Definition: qglobal.h:2214
QImageData * DataPtr
Definition: qimage.h:345
unsigned char uchar
Definition: qglobal.h:994
#define QT_BEGIN_NAMESPACE
This macro expands to.
Definition: qglobal.h:89
int width() const
Definition: qpaintdevice.h:91
void swap(QImage &other)
Swaps image other with this image.
Definition: qimage.h:147
The QStringList class provides a list of strings.
Definition: qstringlist.h:66
TransformationMode
Definition: qnamespace.h:1510
The QImage class provides a hardware-independent image representation that allows direct access to th...
Definition: qimage.h:87
static const char * data(const QByteArray &arr)
unsigned int uint
Definition: qglobal.h:996
__int64 qint64
Definition: qglobal.h:942
The QPaintEngine class provides an abstract definition of how QPainter draws to a given device on a g...
Definition: qpaintengine.h:90
DataPtr & data_ptr()
Definition: qimage.h:346
void qSwap(T &value1, T &value2)
Definition: qglobal.h:2181
QT_DEPRECATED int numColors() const
Definition: qpaintdevice.h:100
bool valid(int x, int y) const
Returns true if QPoint(x, y) is a valid coordinate pair within the image; otherwise returns false...
Definition: qimage.cpp:4165
const char * constData() const
Returns a pointer to the data stored in the byte array.
Definition: qbytearray.h:433
#define Q_REQUIRED_RESULT
Definition: qglobal.h:846
void setPixel(int x, int y, uint index_or_rgb)
Sets the pixel index or color at (x, y) to index_or_rgb.
Definition: qimage.cpp:4311
virtual QPaintEngine * paintEngine() const =0
QByteArray lang
Definition: qimage.h:75
#define load(x)
Q_GUI_EXPORT qint64 qt_image_id(const QImage &image)
Definition: qimage.cpp:117
int key
The QPoint class defines a point in the plane using integer precision.
Definition: qpoint.h:53
The QRect class defines a rectangle in the plane using integer precision.
Definition: qrect.h:58
QFactoryLoader * l
int size() const
Returns the number of bytes in this byte array.
Definition: qbytearray.h:402
virtual int metric(PaintDeviceMetric metric) const
int y() const
Returns the y coordinate of this point.
Definition: qpoint.h:131
int depth() const
Definition: qpaintdevice.h:103
#define Q_GUI_EXPORT_INLINE
Definition: qglobal.h:1494
#define QT_DEPRECATED
Definition: qglobal.h:1094
static QImage fromData(const QByteArray &data, const char *format=0)
This is an overloaded member function, provided for convenience. It differs from the above function o...
Definition: qimage.h:258
const QVector< QRgb > * qt_image_colortable(const QImage &image)
Definition: qimage.cpp:122
The QSize class defines the size of a two-dimensional object using integer point precision.
Definition: qsize.h:53
The QDataStream class provides serialization of binary data to a QIODevice.
Definition: qdatastream.h:71
Q_DECLARE_TYPEINFO(QImage, Q_MOVABLE_TYPE)
int x() const
Returns the x coordinate of this point.
Definition: qpoint.h:128
QImage scaled(int w, int h, Qt::AspectRatioMode aspectMode=Qt::IgnoreAspectRatio, Qt::TransformationMode mode=Qt::FastTransformation) const
Definition: qimage.h:232
The QIODevice class is the base interface class of all I/O devices in Qt.
Definition: qiodevice.h:66
bool loadFromData(const QByteArray &data, const char *aformat=0)
This is an overloaded member function, provided for convenience. It differs from the above function o...
Definition: qimage.h:251
#define QT_END_HEADER
Definition: qglobal.h:137
static QString fileName(const QString &fileUrl)
bool operator==(QBool b1, bool b2)
Definition: qglobal.h:2023
static QImage fromData(const uchar *data, int size, const char *format=0)
Constructs a QImage from the first size bytes of the given binary data.
Definition: qimage.cpp:5313
QByteArray key
Definition: qimage.h:74
static bool isNull(const QVariant::Private *d)
Definition: qvariant.cpp:300
#define text
Definition: qobjectdefs.h:80
The QTransform class specifies 2D transformations of a coordinate system.
Definition: qtransform.h:65
The QList class is a template class that provides lists.
Definition: qdatastream.h:62
AspectRatioMode
Definition: qnamespace.h:1317