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