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#include <QtCore/qcontainerfwd.h>
53
54#if defined(Q_OS_DARWIN) || defined(Q_QDOC)
55Q_FORWARD_DECLARE_MUTABLE_CG_TYPE(CGImage);
56#endif
57
58QT_BEGIN_NAMESPACE
59
60
61class QColorSpace;
62class QColorTransform;
63class QIODevice;
64class QTransform;
65class QVariant;
66
67struct QImageData;
68
69typedef void (*QImageCleanupFunction)(void*);
70
71class Q_GUI_EXPORT QImage : public QPaintDevice
72{
73 Q_GADGET
74public:
75 enum InvertMode { InvertRgb, InvertRgba };
76 enum Format {
77 Format_Invalid,
78 Format_Mono,
79 Format_MonoLSB,
80 Format_Indexed8,
81 Format_RGB32,
82 Format_ARGB32,
83 Format_ARGB32_Premultiplied,
84 Format_RGB16,
85 Format_ARGB8565_Premultiplied,
86 Format_RGB666,
87 Format_ARGB6666_Premultiplied,
88 Format_RGB555,
89 Format_ARGB8555_Premultiplied,
90 Format_RGB888,
91 Format_RGB444,
92 Format_ARGB4444_Premultiplied,
93 Format_RGBX8888,
94 Format_RGBA8888,
95 Format_RGBA8888_Premultiplied,
96 Format_BGR30,
97 Format_A2BGR30_Premultiplied,
98 Format_RGB30,
99 Format_A2RGB30_Premultiplied,
100 Format_Alpha8,
101 Format_Grayscale8,
102 Format_RGBX64,
103 Format_RGBA64,
104 Format_RGBA64_Premultiplied,
105 Format_Grayscale16,
106 Format_BGR888,
107#ifndef Q_QDOC
108 NImageFormats
109#endif
110 };
111 Q_ENUM(Format)
112
113 QImage() noexcept;
114 QImage(const QSize &size, Format format);
115 QImage(int width, int height, Format format);
116 QImage(uchar *data, int width, int height, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
117 QImage(const uchar *data, int width, int height, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
118 QImage(uchar *data, int width, int height, qsizetype bytesPerLine, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
119 QImage(const uchar *data, int width, int height, qsizetype bytesPerLine, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
120
121#ifndef QT_NO_IMAGEFORMAT_XPM
122 explicit QImage(const char * const xpm[]);
123#endif
124 explicit QImage(const QString &fileName, const char *format = nullptr);
125
126 QImage(const QImage &);
127 QImage(QImage &&other) noexcept
128 : QPaintDevice(), d(qExchange(other.d, nullptr))
129 {}
130 ~QImage();
131
132 QImage &operator=(const QImage &);
133 QT_MOVE_ASSIGNMENT_OPERATOR_IMPL_VIA_MOVE_AND_SWAP(QImage)
134 void swap(QImage &other) noexcept
135 { qSwap(d, other.d); }
136
137 bool isNull() const;
138
139 int devType() const override;
140
141 bool operator==(const QImage &) const;
142 bool operator!=(const QImage &) const;
143 operator QVariant() const;
144 void detach();
145 bool isDetached() const;
146
147 [[nodiscard]] QImage copy(const QRect &rect = QRect()) const;
148 [[nodiscard]] QImage copy(int x, int y, int w, int h) const
149 { return copy(QRect(x, y, w, h)); }
150
151 Format format() const;
152
153 [[nodiscard]] QImage convertToFormat(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) const &
154 { return convertToFormat_helper(f, flags); }
155 [[nodiscard]] QImage convertToFormat(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) &&
156 {
157 if (convertToFormat_inplace(f, flags))
158 return std::move(*this);
159 else
160 return convertToFormat_helper(f, flags);
161 }
162 [[nodiscard]] QImage convertToFormat(Format f, const QList<QRgb> &colorTable,
163 Qt::ImageConversionFlags flags = Qt::AutoColor) const;
164
165 bool reinterpretAsFormat(Format f);
166 [[nodiscard]] QImage convertedTo(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) const &
167 { return convertToFormat(f, flags); }
168 [[nodiscard]] QImage convertedTo(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) &&
169 { return convertToFormat(f, flags); }
170 void convertTo(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor);
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 qsizetype sizeInBytes() const;
193
194 uchar *scanLine(int);
195 const uchar *scanLine(int) const;
196 const uchar *constScanLine(int) const;
197 qsizetype 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 QColor pixelColor(int x, int y) const;
212 QColor pixelColor(const QPoint &pt) const;
213
214 void setPixelColor(int x, int y, const QColor &c);
215 void setPixelColor(const QPoint &pt, const QColor &c);
216
217 QList<QRgb> colorTable() const;
218 void setColorTable(const QList<QRgb> &colors);
219
220 qreal devicePixelRatio() const;
221 void setDevicePixelRatio(qreal scaleFactor);
222 QSizeF deviceIndependentSize() const;
223
224 void fill(uint pixel);
225 void fill(const QColor &color);
226 void fill(Qt::GlobalColor color);
227
228
229 bool hasAlphaChannel() const;
230 void setAlphaChannel(const QImage &alphaChannel);
231 [[nodiscard]] QImage createAlphaMask(Qt::ImageConversionFlags flags = Qt::AutoColor) const;
232#ifndef QT_NO_IMAGE_HEURISTIC_MASK
233 [[nodiscard]] QImage createHeuristicMask(bool clipTight = true) const;
234#endif
235 [[nodiscard]] QImage createMaskFromColor(QRgb color, Qt::MaskMode mode = Qt::MaskInColor) const;
236
237 [[nodiscard]] QImage scaled(int w, int h, Qt::AspectRatioMode aspectMode = Qt::IgnoreAspectRatio,
238 Qt::TransformationMode mode = Qt::FastTransformation) const
239 { return scaled(QSize(w, h), aspectMode, mode); }
240 [[nodiscard]] QImage scaled(const QSize &s, Qt::AspectRatioMode aspectMode = Qt::IgnoreAspectRatio,
241 Qt::TransformationMode mode = Qt::FastTransformation) const;
242 [[nodiscard]] QImage scaledToWidth(int w, Qt::TransformationMode mode = Qt::FastTransformation) const;
243 [[nodiscard]] QImage scaledToHeight(int h, Qt::TransformationMode mode = Qt::FastTransformation) const;
244 [[nodiscard]] QImage transformed(const QTransform &matrix, Qt::TransformationMode mode = Qt::FastTransformation) const;
245 static QTransform trueMatrix(const QTransform &, int w, int h);
246
247 [[nodiscard]] QImage mirrored(bool horizontally = false, bool vertically = true) const &
248 { return mirrored_helper(horizontally, vertically); }
249 [[nodiscard]] QImage mirrored(bool horizontally = false, bool vertically = true) &&
250 { mirrored_inplace(horizontally, vertically); return std::move(*this); }
251 [[nodiscard]] QImage rgbSwapped() const &
252 { return rgbSwapped_helper(); }
253 [[nodiscard]] QImage rgbSwapped() &&
254 { rgbSwapped_inplace(); return std::move(*this); }
255 void mirror(bool horizontally = false, bool vertically = true)
256 { mirrored_inplace(horizontally, vertically); }
257 void rgbSwap()
258 { rgbSwapped_inplace(); }
259 void invertPixels(InvertMode = InvertRgb);
260
261 QColorSpace colorSpace() const;
262 [[nodiscard]] QImage convertedToColorSpace(const QColorSpace &) const;
263 void convertToColorSpace(const QColorSpace &);
264 void setColorSpace(const QColorSpace &);
265
266 void applyColorTransform(const QColorTransform &transform);
267
268 bool load(QIODevice *device, const char *format);
269 bool load(const QString &fileName, const char *format = nullptr);
270 bool loadFromData(const uchar *buf, int len, const char *format = nullptr);
271 bool loadFromData(const QByteArray &data, const char *aformat = nullptr)
272 { return loadFromData(reinterpret_cast<const uchar *>(data.constData()), data.size(), aformat); }
273
274 bool save(const QString &fileName, const char *format = nullptr, int quality = -1) const;
275 bool save(QIODevice *device, const char *format = nullptr, int quality = -1) const;
276
277 static QImage fromData(const uchar *data, int size, const char *format = nullptr);
278 static QImage fromData(const QByteArray &data, const char *format = nullptr)
279 { return fromData(reinterpret_cast<const uchar *>(data.constData()), data.size(), format); }
280
281 qint64 cacheKey() const;
282
283 QPaintEngine *paintEngine() const override;
284
285 // Auxiliary data
286 int dotsPerMeterX() const;
287 int dotsPerMeterY() const;
288 void setDotsPerMeterX(int);
289 void setDotsPerMeterY(int);
290 QPoint offset() const;
291 void setOffset(const QPoint&);
292
293 QStringList textKeys() const;
294 QString text(const QString &key = QString()) const;
295 void setText(const QString &key, const QString &value);
296
297 QPixelFormat pixelFormat() const noexcept;
298 static QPixelFormat toPixelFormat(QImage::Format format) noexcept;
299 static QImage::Format toImageFormat(QPixelFormat format) noexcept;
300
301 // Platform specific conversion functions
302#if defined(Q_OS_DARWIN) || defined(Q_QDOC)
303 CGImageRef toCGImage() const Q_DECL_CF_RETURNS_RETAINED;
304#endif
305#if defined(Q_OS_WIN) || defined(Q_QDOC)
306 HBITMAP toHBITMAP() const;
307 HICON toHICON(const QImage &mask = {}) const;
308 static QImage fromHBITMAP(HBITMAP hbitmap);
309 static QImage fromHICON(HICON icon);
310#endif
311
312protected:
313 virtual int metric(PaintDeviceMetric metric) const override;
314 QImage mirrored_helper(bool horizontal, bool vertical) const;
315 QImage rgbSwapped_helper() const;
316 void mirrored_inplace(bool horizontal, bool vertical);
317 void rgbSwapped_inplace();
318 QImage convertToFormat_helper(Format format, Qt::ImageConversionFlags flags) const;
319 bool convertToFormat_inplace(Format format, Qt::ImageConversionFlags flags);
320 QImage smoothScaled(int w, int h) const;
321
322private:
323 QImageData *d;
324
325 friend class QRasterPlatformPixmap;
326 friend class QBlittablePlatformPixmap;
327 friend class QPixmapCacheEntry;
328 friend struct QImageData;
329
330public:
331 typedef QImageData * DataPtr;
332 inline DataPtr &data_ptr() { return d; }
333};
334
335Q_DECLARE_SHARED(QImage)
336
337// Inline functions...
338
339inline bool QImage::valid(const QPoint &pt) const { return valid(pt.x(), pt.y()); }
340inline int QImage::pixelIndex(const QPoint &pt) const { return pixelIndex(pt.x(), pt.y());}
341inline QRgb QImage::pixel(const QPoint &pt) const { return pixel(pt.x(), pt.y()); }
342inline void QImage::setPixel(const QPoint &pt, uint index_or_rgb) { setPixel(pt.x(), pt.y(), index_or_rgb); }
343inline QColor QImage::pixelColor(const QPoint &pt) const { return pixelColor(pt.x(), pt.y()); }
344inline void QImage::setPixelColor(const QPoint &pt, const QColor &c) { setPixelColor(pt.x(), pt.y(), c); }
345
346// QImage stream functions
347
348#if !defined(QT_NO_DATASTREAM)
349Q_GUI_EXPORT QDataStream &operator<<(QDataStream &, const QImage &);
350Q_GUI_EXPORT QDataStream &operator>>(QDataStream &, QImage &);
351#endif
352
353#ifndef QT_NO_DEBUG_STREAM
354Q_GUI_EXPORT QDebug operator<<(QDebug, const QImage &);
355#endif
356
357
358QT_END_NAMESPACE
359
360#endif // QIMAGE_H
361