1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
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 The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/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 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#ifndef QIMAGE_H
41#define QIMAGE_H
42
43#include <QtGui/qtguiglobal.h>
44#include <QtGui/qcolor.h>
45#include <QtGui/qrgb.h>
46#include <QtGui/qpaintdevice.h>
47#include <QtGui/qpixelformat.h>
48#include <QtGui/qtransform.h>
49#include <QtCore/qbytearray.h>
50#include <QtCore/qrect.h>
51#include <QtCore/qstring.h>
52
53#if QT_DEPRECATED_SINCE(5, 0)
54#include <QtCore/qstringlist.h>
55#endif
56
57#if defined(Q_OS_DARWIN) || defined(Q_QDOC)
58Q_FORWARD_DECLARE_MUTABLE_CG_TYPE(CGImage);
59#endif
60
61QT_BEGIN_NAMESPACE
62
63
64class QColorSpace;
65class QColorTransform;
66class QIODevice;
67class QMatrix;
68class QStringList;
69class QTransform;
70class QVariant;
71template <class T> class QList;
72template <class T> class QVector;
73
74struct QImageData;
75class QImageDataMisc; // internal
76#if QT_DEPRECATED_SINCE(5, 0)
77class QImageTextKeyLang {
78public:
79 QT_DEPRECATED QImageTextKeyLang(const char* k, const char* l) : key(k), lang(l) { }
80 QT_DEPRECATED QImageTextKeyLang() { }
81
82 QByteArray key;
83 QByteArray lang;
84
85 bool operator< (const QImageTextKeyLang& other) const
86 { return key < other.key || (key==other.key && lang < other.lang); }
87 bool operator== (const QImageTextKeyLang& other) const
88 { return key==other.key && lang==other.lang; }
89 inline bool operator!= (const QImageTextKeyLang &other) const
90 { return !operator==(other); }
91private:
92 friend class QImage;
93 QImageTextKeyLang(bool /*dummy*/) {}
94};
95#endif
96
97typedef void (*QImageCleanupFunction)(void*);
98
99class Q_GUI_EXPORT QImage : public QPaintDevice
100{
101 Q_GADGET
102public:
103 enum InvertMode { InvertRgb, InvertRgba };
104 enum Format {
105 Format_Invalid,
106 Format_Mono,
107 Format_MonoLSB,
108 Format_Indexed8,
109 Format_RGB32,
110 Format_ARGB32,
111 Format_ARGB32_Premultiplied,
112 Format_RGB16,
113 Format_ARGB8565_Premultiplied,
114 Format_RGB666,
115 Format_ARGB6666_Premultiplied,
116 Format_RGB555,
117 Format_ARGB8555_Premultiplied,
118 Format_RGB888,
119 Format_RGB444,
120 Format_ARGB4444_Premultiplied,
121 Format_RGBX8888,
122 Format_RGBA8888,
123 Format_RGBA8888_Premultiplied,
124 Format_BGR30,
125 Format_A2BGR30_Premultiplied,
126 Format_RGB30,
127 Format_A2RGB30_Premultiplied,
128 Format_Alpha8,
129 Format_Grayscale8,
130 Format_RGBX64,
131 Format_RGBA64,
132 Format_RGBA64_Premultiplied,
133 Format_Grayscale16,
134#ifndef Q_QDOC
135 NImageFormats
136#endif
137 };
138 Q_ENUM(Format)
139
140 QImage() Q_DECL_NOEXCEPT;
141 QImage(const QSize &size, Format format);
142 QImage(int width, int height, Format format);
143 QImage(uchar *data, int width, int height, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
144 QImage(const uchar *data, int width, int height, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
145 QImage(uchar *data, int width, int height, int bytesPerLine, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
146 QImage(const uchar *data, int width, int height, int bytesPerLine, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
147
148#ifndef QT_NO_IMAGEFORMAT_XPM
149 explicit QImage(const char * const xpm[]);
150#endif
151 explicit QImage(const QString &fileName, const char *format = nullptr);
152
153 QImage(const QImage &);
154#ifdef Q_COMPILER_RVALUE_REFS
155 inline QImage(QImage &&other) Q_DECL_NOEXCEPT
156 : QPaintDevice(), d(nullptr)
157 { qSwap(d, other.d); }
158#endif
159 ~QImage();
160
161 QImage &operator=(const QImage &);
162#ifdef Q_COMPILER_RVALUE_REFS
163 inline QImage &operator=(QImage &&other) Q_DECL_NOEXCEPT
164 { qSwap(d, other.d); return *this; }
165#endif
166 inline void swap(QImage &other) Q_DECL_NOEXCEPT
167 { qSwap(d, other.d); }
168
169 bool isNull() const;
170
171 int devType() const override;
172
173 bool operator==(const QImage &) const;
174 bool operator!=(const QImage &) const;
175 operator QVariant() const;
176 void detach();
177 bool isDetached() const;
178
179 QImage copy(const QRect &rect = QRect()) const;
180 inline QImage copy(int x, int y, int w, int h) const
181 { return copy(QRect(x, y, w, h)); }
182
183 Format format() const;
184
185#if defined(Q_COMPILER_REF_QUALIFIERS) && !defined(QT_COMPILING_QIMAGE_COMPAT_CPP)
186 Q_REQUIRED_RESULT Q_ALWAYS_INLINE QImage convertToFormat(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) const &
187 { return convertToFormat_helper(f, flags); }
188 Q_REQUIRED_RESULT Q_ALWAYS_INLINE QImage convertToFormat(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) &&
189 {
190 if (convertToFormat_inplace(f, flags))
191 return std::move(*this);
192 else
193 return convertToFormat_helper(f, flags);
194 }
195#else
196 Q_REQUIRED_RESULT QImage convertToFormat(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) const;
197#endif
198 Q_REQUIRED_RESULT QImage convertToFormat(Format f, const QVector<QRgb> &colorTable, Qt::ImageConversionFlags flags = Qt::AutoColor) const;
199 bool reinterpretAsFormat(Format f);
200
201 void convertTo(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor);
202
203 int width() const;
204 int height() const;
205 QSize size() const;
206 QRect rect() const;
207
208 int depth() const;
209 int colorCount() const;
210 int bitPlaneCount() const;
211
212 QRgb color(int i) const;
213 void setColor(int i, QRgb c);
214 void setColorCount(int);
215
216 bool allGray() const;
217 bool isGrayscale() const;
218
219 uchar *bits();
220 const uchar *bits() const;
221 const uchar *constBits() const;
222
223#if QT_DEPRECATED_SINCE(5, 10)
224 QT_DEPRECATED_X("Use sizeInBytes") int byteCount() const;
225#endif
226 qsizetype sizeInBytes() const;
227
228 uchar *scanLine(int);
229 const uchar *scanLine(int) const;
230 const uchar *constScanLine(int) const;
231#if QT_VERSION >= QT_VERSION_CHECK(6,0,0)
232 qsizetype bytesPerLine() const;
233#else
234 int bytesPerLine() const;
235#endif
236
237 bool valid(int x, int y) const;
238 bool valid(const QPoint &pt) const;
239
240 int pixelIndex(int x, int y) const;
241 int pixelIndex(const QPoint &pt) const;
242
243 QRgb pixel(int x, int y) const;
244 QRgb pixel(const QPoint &pt) const;
245
246 void setPixel(int x, int y, uint index_or_rgb);
247 void setPixel(const QPoint &pt, uint index_or_rgb);
248
249 QColor pixelColor(int x, int y) const;
250 QColor pixelColor(const QPoint &pt) const;
251
252 void setPixelColor(int x, int y, const QColor &c);
253 void setPixelColor(const QPoint &pt, const QColor &c);
254
255 QVector<QRgb> colorTable() const;
256#if QT_VERSION >= QT_VERSION_CHECK(6,0,0)
257 void setColorTable(const QVector<QRgb> &colors);
258#else
259 void setColorTable(const QVector<QRgb> colors);
260#endif
261
262 qreal devicePixelRatio() const;
263 void setDevicePixelRatio(qreal scaleFactor);
264
265 void fill(uint pixel);
266 void fill(const QColor &color);
267 void fill(Qt::GlobalColor color);
268
269
270 bool hasAlphaChannel() const;
271 void setAlphaChannel(const QImage &alphaChannel);
272 QImage alphaChannel() const;
273 QImage createAlphaMask(Qt::ImageConversionFlags flags = Qt::AutoColor) const;
274#ifndef QT_NO_IMAGE_HEURISTIC_MASK
275 QImage createHeuristicMask(bool clipTight = true) const;
276#endif
277 QImage createMaskFromColor(QRgb color, Qt::MaskMode mode = Qt::MaskInColor) const;
278
279 inline QImage scaled(int w, int h, Qt::AspectRatioMode aspectMode = Qt::IgnoreAspectRatio,
280 Qt::TransformationMode mode = Qt::FastTransformation) const
281 { return scaled(QSize(w, h), aspectMode, mode); }
282 QImage scaled(const QSize &s, Qt::AspectRatioMode aspectMode = Qt::IgnoreAspectRatio,
283 Qt::TransformationMode mode = Qt::FastTransformation) const;
284 QImage scaledToWidth(int w, Qt::TransformationMode mode = Qt::FastTransformation) const;
285 QImage scaledToHeight(int h, Qt::TransformationMode mode = Qt::FastTransformation) const;
286 QImage transformed(const QMatrix &matrix, Qt::TransformationMode mode = Qt::FastTransformation) const;
287 static QMatrix trueMatrix(const QMatrix &, int w, int h);
288 QImage transformed(const QTransform &matrix, Qt::TransformationMode mode = Qt::FastTransformation) const;
289 static QTransform trueMatrix(const QTransform &, int w, int h);
290#if defined(Q_COMPILER_REF_QUALIFIERS) && !defined(QT_COMPILING_QIMAGE_COMPAT_CPP)
291 QImage mirrored(bool horizontally = false, bool vertically = true) const &
292 { return mirrored_helper(horizontally, vertically); }
293 QImage &&mirrored(bool horizontally = false, bool vertically = true) &&
294 { mirrored_inplace(horizontally, vertically); return qMove(*this); }
295 QImage rgbSwapped() const &
296 { return rgbSwapped_helper(); }
297 QImage &&rgbSwapped() &&
298 { rgbSwapped_inplace(); return qMove(*this); }
299#else
300 QImage mirrored(bool horizontally = false, bool vertically = true) const;
301 QImage rgbSwapped() const;
302#endif
303 void invertPixels(InvertMode = InvertRgb);
304
305 QColorSpace colorSpace() const;
306 QImage convertedToColorSpace(const QColorSpace &) const;
307 void convertToColorSpace(const QColorSpace &);
308 void setColorSpace(const QColorSpace &);
309
310 void applyColorTransform(const QColorTransform &transform);
311
312 bool load(QIODevice *device, const char* format);
313 bool load(const QString &fileName, const char *format = nullptr);
314 bool loadFromData(const uchar *buf, int len, const char *format = nullptr);
315 inline bool loadFromData(const QByteArray &data, const char *aformat = nullptr)
316 { return loadFromData(reinterpret_cast<const uchar *>(data.constData()), data.size(), aformat); }
317
318 bool save(const QString &fileName, const char *format = nullptr, int quality = -1) const;
319 bool save(QIODevice *device, const char *format = nullptr, int quality = -1) const;
320
321 static QImage fromData(const uchar *data, int size, const char *format = nullptr);
322 inline static QImage fromData(const QByteArray &data, const char *format = nullptr)
323 { return fromData(reinterpret_cast<const uchar *>(data.constData()), data.size(), format); }
324
325#if QT_DEPRECATED_SINCE(5, 0)
326 QT_DEPRECATED inline int serialNumber() const { return cacheKey() >> 32; }
327#endif
328 qint64 cacheKey() const;
329
330 QPaintEngine *paintEngine() const override;
331
332 // Auxiliary data
333 int dotsPerMeterX() const;
334 int dotsPerMeterY() const;
335 void setDotsPerMeterX(int);
336 void setDotsPerMeterY(int);
337 QPoint offset() const;
338 void setOffset(const QPoint&);
339
340 QStringList textKeys() const;
341 QString text(const QString &key = QString()) const;
342 void setText(const QString &key, const QString &value);
343
344 QPixelFormat pixelFormat() const Q_DECL_NOTHROW;
345 static QPixelFormat toPixelFormat(QImage::Format format) Q_DECL_NOTHROW;
346 static QImage::Format toImageFormat(QPixelFormat format) Q_DECL_NOTHROW;
347
348 // Platform specific conversion functions
349#if defined(Q_OS_DARWIN) || defined(Q_QDOC)
350 CGImageRef toCGImage() const Q_DECL_CF_RETURNS_RETAINED;
351#endif
352
353#if QT_DEPRECATED_SINCE(5, 0)
354 QT_DEPRECATED inline QString text(const char *key, const char *lang = nullptr) const;
355 QT_DEPRECATED inline QList<QImageTextKeyLang> textList() const;
356 QT_DEPRECATED inline QStringList textLanguages() const;
357 QT_DEPRECATED inline QString text(const QImageTextKeyLang&) const;
358 QT_DEPRECATED inline void setText(const char* key, const char* lang, const QString&);
359#endif
360
361#if QT_DEPRECATED_SINCE(5, 0)
362 QT_DEPRECATED inline int numColors() const;
363 QT_DEPRECATED inline void setNumColors(int);
364 QT_DEPRECATED inline int numBytes() const;
365#endif
366
367protected:
368 virtual int metric(PaintDeviceMetric metric) const override;
369 QImage mirrored_helper(bool horizontal, bool vertical) const;
370 QImage rgbSwapped_helper() const;
371 void mirrored_inplace(bool horizontal, bool vertical);
372 void rgbSwapped_inplace();
373 QImage convertToFormat_helper(Format format, Qt::ImageConversionFlags flags) const;
374 bool convertToFormat_inplace(Format format, Qt::ImageConversionFlags flags);
375 QImage smoothScaled(int w, int h) const;
376
377private:
378 friend class QWSOnScreenSurface;
379 QImageData *d;
380
381 friend class QRasterPlatformPixmap;
382 friend class QBlittablePlatformPixmap;
383 friend class QPixmapCacheEntry;
384
385public:
386 typedef QImageData * DataPtr;
387 inline DataPtr &data_ptr() { return d; }
388};
389
390Q_DECLARE_SHARED(QImage)
391
392// Inline functions...
393
394inline bool QImage::valid(const QPoint &pt) const { return valid(pt.x(), pt.y()); }
395inline int QImage::pixelIndex(const QPoint &pt) const { return pixelIndex(pt.x(), pt.y());}
396inline QRgb QImage::pixel(const QPoint &pt) const { return pixel(pt.x(), pt.y()); }
397inline void QImage::setPixel(const QPoint &pt, uint index_or_rgb) { setPixel(pt.x(), pt.y(), index_or_rgb); }
398inline QColor QImage::pixelColor(const QPoint &pt) const { return pixelColor(pt.x(), pt.y()); }
399inline void QImage::setPixelColor(const QPoint &pt, const QColor &c) { setPixelColor(pt.x(), pt.y(), c); }
400
401#if QT_DEPRECATED_SINCE(5, 0)
402
403QT_WARNING_PUSH
404QT_WARNING_DISABLE_DEPRECATED
405
406inline QString QImage::text(const char* key, const char* lang) const
407{
408 if (!d)
409 return QString();
410 QString k = QString::fromLatin1(key);
411 if (lang && *lang)
412 k += QLatin1Char('/') + QString::fromLatin1(lang);
413 return text(k);
414}
415
416inline QList<QImageTextKeyLang> QImage::textList() const
417{
418 QList<QImageTextKeyLang> imageTextKeys;
419 if (!d)
420 return imageTextKeys;
421 QStringList keys = textKeys();
422 for (int i = 0; i < keys.size(); ++i) {
423 int index = keys.at(i).indexOf(QLatin1Char('/'));
424 if (index > 0) {
425 QImageTextKeyLang tkl(true);
426 tkl.key = keys.at(i).left(index).toLatin1();
427 tkl.lang = keys.at(i).mid(index+1).toLatin1();
428 imageTextKeys += tkl;
429 }
430 }
431
432 return imageTextKeys;
433}
434
435inline QStringList QImage::textLanguages() const
436{
437 if (!d)
438 return QStringList();
439 QStringList keys = textKeys();
440 QStringList languages;
441 for (int i = 0; i < keys.size(); ++i) {
442 int index = keys.at(i).indexOf(QLatin1Char('/'));
443 if (index > 0)
444 languages += keys.at(i).mid(index+1);
445 }
446
447 return languages;
448}
449
450inline QString QImage::text(const QImageTextKeyLang&kl) const
451{
452 if (!d)
453 return QString();
454 QString k = QString::fromLatin1(kl.key.constData());
455 if (!kl.lang.isEmpty())
456 k += QLatin1Char('/') + QString::fromLatin1(kl.lang.constData());
457 return text(k);
458}
459
460inline void QImage::setText(const char* key, const char* lang, const QString &s)
461{
462 if (!d)
463 return;
464 detach();
465
466 // In case detach() ran out of memory
467 if (!d)
468 return;
469
470 QString k = QString::fromLatin1(key);
471 if (lang && *lang)
472 k += QLatin1Char('/') + QString::fromLatin1(lang);
473 setText(k, s);
474}
475
476QT_WARNING_POP
477
478inline int QImage::numColors() const
479{
480 return colorCount();
481}
482
483inline void QImage::setNumColors(int n)
484{
485 setColorCount(n);
486}
487
488inline int QImage::numBytes() const
489{
490 return int(sizeInBytes());
491}
492#endif
493
494// QImage stream functions
495
496#if !defined(QT_NO_DATASTREAM)
497Q_GUI_EXPORT QDataStream &operator<<(QDataStream &, const QImage &);
498Q_GUI_EXPORT QDataStream &operator>>(QDataStream &, QImage &);
499#endif
500
501#ifndef QT_NO_DEBUG_STREAM
502Q_GUI_EXPORT QDebug operator<<(QDebug, const QImage &);
503#endif
504
505
506QT_END_NAMESPACE
507
508#endif // QIMAGE_H
509