Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qimage.h
Go to the documentation of this file.
1// Copyright (C) 2021 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3// Qt-Security score:significant reason:default
4
5#ifndef QIMAGE_H
6#define QIMAGE_H
7
8#include <QtGui/qtguiglobal.h>
9#include <QtGui/qcolor.h>
10#include <QtGui/qrgb.h>
11#include <QtGui/qpaintdevice.h>
12#include <QtGui/qpixelformat.h>
13#include <QtGui/qtransform.h>
14#include <QtCore/qbytearray.h>
15#include <QtCore/qbytearrayview.h>
16#include <QtCore/qrect.h>
17#include <QtCore/qstring.h>
18#include <QtCore/qcontainerfwd.h>
19
20#if defined(Q_OS_DARWIN) || defined(Q_QDOC)
21Q_FORWARD_DECLARE_MUTABLE_CG_TYPE(CGImage);
22#endif
23
24QT_BEGIN_NAMESPACE
25
26
27class QColorSpace;
28class QColorTransform;
29class QIODevice;
30class QTransform;
31class QVariant;
32
33struct QImageData;
34
35typedef void (*QImageCleanupFunction)(void*);
36
37class Q_GUI_EXPORT QImage : public QPaintDevice
38{
39 Q_GADGET
40public:
41 enum InvertMode { InvertRgb, InvertRgba };
42 enum Format {
43 Format_Invalid,
44 Format_Mono,
45 Format_MonoLSB,
46 Format_Indexed8,
47 Format_RGB32,
48 Format_ARGB32,
49 Format_ARGB32_Premultiplied,
50 Format_RGB16,
51 Format_ARGB8565_Premultiplied,
52 Format_RGB666,
53 Format_ARGB6666_Premultiplied,
54 Format_RGB555,
55 Format_ARGB8555_Premultiplied,
56 Format_RGB888,
57 Format_RGB444,
58 Format_ARGB4444_Premultiplied,
59 Format_RGBX8888,
60 Format_RGBA8888,
61 Format_RGBA8888_Premultiplied,
62 Format_BGR30,
63 Format_A2BGR30_Premultiplied,
64 Format_RGB30,
65 Format_A2RGB30_Premultiplied,
66 Format_Alpha8,
67 Format_Grayscale8,
68 Format_RGBX64,
69 Format_RGBA64,
70 Format_RGBA64_Premultiplied,
71 Format_Grayscale16,
72 Format_BGR888,
73 Format_RGBX16FPx4,
74 Format_RGBA16FPx4,
75 Format_RGBA16FPx4_Premultiplied,
76 Format_RGBX32FPx4,
77 Format_RGBA32FPx4,
78 Format_RGBA32FPx4_Premultiplied,
79 Format_CMYK8888,
80#ifndef Q_QDOC
81 NImageFormats
82#endif
83 };
84 Q_ENUM(Format)
85
86 QImage() noexcept;
87 QImage(const QSize &size, Format format);
88 QImage(int width, int height, Format format);
89 QImage(uchar *data, int width, int height, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
90 QImage(const uchar *data, int width, int height, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
91 QImage(uchar *data, int width, int height, qsizetype bytesPerLine, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
92 QImage(const uchar *data, int width, int height, qsizetype bytesPerLine, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
93
94#ifndef QT_NO_IMAGEFORMAT_XPM
95 explicit QImage(const char * const xpm[]);
96#endif
97 explicit QImage(const QString &fileName, const char *format = nullptr);
98
99 QImage(const QImage &);
100 QImage(QImage &&other) noexcept
101 : QPaintDevice(), d(std::exchange(other.d, nullptr))
102 {}
103 ~QImage();
104
105 QImage &operator=(const QImage &);
106 QT_MOVE_ASSIGNMENT_OPERATOR_IMPL_VIA_MOVE_AND_SWAP(QImage)
107 void swap(QImage &other) noexcept
108 { qt_ptr_swap(d, other.d); }
109
110 bool isNull() const;
111
112 int devType() const override;
113
114 bool operator==(const QImage &) const;
115 bool operator!=(const QImage &) const;
116 operator QVariant() const;
117 void detach();
118 bool isDetached() const;
119
120 [[nodiscard]] QImage copy(const QRect &rect = QRect()) const;
121 [[nodiscard]] QImage copy(int x, int y, int w, int h) const
122 { return copy(QRect(x, y, w, h)); }
123
124 Format format() const;
125
126 [[nodiscard]] QImage convertToFormat(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) const &
127 { return convertToFormat_helper(f, flags); }
128 [[nodiscard]] QImage convertToFormat(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) &&
129 {
130 if (convertToFormat_inplace(f, flags))
131 return std::move(*this);
132 else
133 return convertToFormat_helper(f, flags);
134 }
135 [[nodiscard]] QImage convertToFormat(Format f, const QList<QRgb> &colorTable,
136 Qt::ImageConversionFlags flags = Qt::AutoColor) const;
137
138 bool reinterpretAsFormat(Format f);
139 [[nodiscard]] QImage convertedTo(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) const &
140 { return convertToFormat(f, flags); }
141 [[nodiscard]] QImage convertedTo(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) &&
142 { return convertToFormat(f, flags); }
143 void convertTo(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor);
144
145 int width() const;
146 int height() const;
147 QSize size() const;
148 QRect rect() const;
149
150 int depth() const;
151 int colorCount() const;
152 int bitPlaneCount() const;
153
154 QRgb color(int i) const;
155 void setColor(int i, QRgb c);
156 void setColorCount(int);
157
158 bool allGray() const;
159 bool isGrayscale() const;
160
161 uchar *bits();
162 const uchar *bits() const;
163 const uchar *constBits() const;
164
165 qsizetype sizeInBytes() const;
166
167 uchar *scanLine(int);
168 const uchar *scanLine(int) const;
169 const uchar *constScanLine(int) const;
170 qsizetype bytesPerLine() const;
171
172 bool valid(int x, int y) const;
173 bool valid(const QPoint &pt) const;
174
175 int pixelIndex(int x, int y) const;
176 int pixelIndex(const QPoint &pt) const;
177
178 QRgb pixel(int x, int y) const;
179 QRgb pixel(const QPoint &pt) const;
180
181 void setPixel(int x, int y, uint index_or_rgb);
182 void setPixel(const QPoint &pt, uint index_or_rgb);
183
184 QColor pixelColor(int x, int y) const;
185 QColor pixelColor(const QPoint &pt) const;
186
187 void setPixelColor(int x, int y, const QColor &c);
188 void setPixelColor(const QPoint &pt, const QColor &c);
189
190 QList<QRgb> colorTable() const;
191 void setColorTable(const QList<QRgb> &colors);
192
193 qreal devicePixelRatio() const;
194 void setDevicePixelRatio(qreal scaleFactor);
195 QSizeF deviceIndependentSize() const;
196
197 void fill(uint pixel);
198 void fill(const QColor &color);
199 void fill(Qt::GlobalColor color);
200
201
202 bool hasAlphaChannel() const;
203 void setAlphaChannel(const QImage &alphaChannel);
204 [[nodiscard]] QImage createAlphaMask(Qt::ImageConversionFlags flags = Qt::AutoColor) const;
205#ifndef QT_NO_IMAGE_HEURISTIC_MASK
206 [[nodiscard]] QImage createHeuristicMask(bool clipTight = true) const;
207#endif
208 [[nodiscard]] QImage createMaskFromColor(QRgb color, Qt::MaskMode mode = Qt::MaskInColor) const;
209
210 [[nodiscard]] QImage scaled(int w, int h, Qt::AspectRatioMode aspectMode = Qt::IgnoreAspectRatio,
211 Qt::TransformationMode mode = Qt::FastTransformation) const
212 { return scaled(QSize(w, h), aspectMode, mode); }
213 [[nodiscard]] QImage scaled(const QSize &s, Qt::AspectRatioMode aspectMode = Qt::IgnoreAspectRatio,
214 Qt::TransformationMode mode = Qt::FastTransformation) const;
215 [[nodiscard]] QImage scaledToWidth(int w, Qt::TransformationMode mode = Qt::FastTransformation) const;
216 [[nodiscard]] QImage scaledToHeight(int h, Qt::TransformationMode mode = Qt::FastTransformation) const;
217 [[nodiscard]] QImage transformed(const QTransform &matrix, Qt::TransformationMode mode = Qt::FastTransformation) const;
218 static QTransform trueMatrix(const QTransform &, int w, int h);
219#if QT_DEPRECATED_SINCE(6, 13)
220 QT_DEPRECATED_VERSION_X_6_13("Use flipped(Qt::Orientations) instead")
221 [[nodiscard]] QImage mirrored(bool horizontally = false, bool vertically = true) const &
222 { return mirrored_helper(horizontally, vertically); }
223 QT_DEPRECATED_VERSION_X_6_13("Use flipped(Qt::Orientations) instead")
224 [[nodiscard]] QImage mirrored(bool horizontally = false, bool vertically = true) &&
225 { mirrored_inplace(horizontally, vertically); return std::move(*this); }
226 QT_DEPRECATED_VERSION_X_6_13("Use flip(Qt::Orientations) instead")
227 void mirror(bool horizontally = false, bool vertically = true)
228 { mirrored_inplace(horizontally, vertically); }
229#endif
230 [[nodiscard]] QImage rgbSwapped() const &
231 { return rgbSwapped_helper(); }
232 [[nodiscard]] QImage rgbSwapped() &&
233 { rgbSwapped_inplace(); return std::move(*this); }
234 [[nodiscard]] QImage flipped(Qt::Orientations orient = Qt::Vertical) const &
235 { return mirrored_helper(orient.testFlag(Qt::Horizontal), orient.testFlag(Qt::Vertical)); }
236 [[nodiscard]] QImage flipped(Qt::Orientations orient = Qt::Vertical) &&
237 { mirrored_inplace(orient.testFlag(Qt::Horizontal), orient.testFlag(Qt::Vertical)); return std::move(*this); }
238 void flip(Qt::Orientations orient = Qt::Vertical)
239 { mirrored_inplace(orient.testFlag(Qt::Horizontal), orient.testFlag(Qt::Vertical)); }
240 void rgbSwap()
241 { rgbSwapped_inplace(); }
242 void invertPixels(InvertMode = InvertRgb);
243
244 QColorSpace colorSpace() const;
245 [[nodiscard]] QImage convertedToColorSpace(const QColorSpace &colorSpace) const;
246 [[nodiscard]] QImage convertedToColorSpace(const QColorSpace &colorSpace, QImage::Format format,
247 Qt::ImageConversionFlags flags = Qt::AutoColor) const &;
248 [[nodiscard]] QImage convertedToColorSpace(const QColorSpace &colorSpace, QImage::Format format,
249 Qt::ImageConversionFlags flags = Qt::AutoColor) &&;
250 void convertToColorSpace(const QColorSpace &colorSpace);
251 void convertToColorSpace(const QColorSpace &colorSpace, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor);
252 void setColorSpace(const QColorSpace &colorSpace);
253
254 QImage colorTransformed(const QColorTransform &transform) const &;
255 QImage colorTransformed(const QColorTransform &transform, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) const &;
256 QImage colorTransformed(const QColorTransform &transform) &&;
257 QImage colorTransformed(const QColorTransform &transform, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) &&;
258 void applyColorTransform(const QColorTransform &transform);
259 void applyColorTransform(const QColorTransform &transform, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor);
260
261 bool load(QIODevice *device, const char *format);
262 bool load(const QString &fileName, const char *format = nullptr);
263 bool loadFromData(QByteArrayView data, const char *format = nullptr);
264 bool loadFromData(const uchar *buf, int len, const char *format = nullptr); // ### Qt 7: qsizetype
265 bool loadFromData(const QByteArray &data, const char *format = nullptr) // ### Qt 7: drop
266 { return loadFromData(QByteArrayView(data), format); }
267
268 bool save(const QString &fileName, const char *format = nullptr, int quality = -1) const;
269 bool save(QIODevice *device, const char *format = nullptr, int quality = -1) const;
270
271 static QImage fromData(QByteArrayView data, const char *format = nullptr);
272 static QImage fromData(const uchar *data, int size, const char *format = nullptr); // ### Qt 7: qsizetype
273 static QImage fromData(const QByteArray &data, const char *format = nullptr) // ### Qt 7: drop
274 { return fromData(QByteArrayView(data), format); }
275
276 qint64 cacheKey() const;
277
278 QPaintEngine *paintEngine() const override;
279
280 // Auxiliary data
281 int dotsPerMeterX() const;
282 int dotsPerMeterY() const;
283 void setDotsPerMeterX(int);
284 void setDotsPerMeterY(int);
285 QPoint offset() const;
286 void setOffset(const QPoint&);
287
288 QStringList textKeys() const;
289 QString text(const QString &key = QString()) const;
290 void setText(const QString &key, const QString &value);
291
292 QPixelFormat pixelFormat() const noexcept;
293 static QPixelFormat toPixelFormat(QImage::Format format) noexcept;
294 static QImage::Format toImageFormat(QPixelFormat format) noexcept;
295
296 // Platform specific conversion functions
297#if defined(Q_OS_DARWIN) || defined(Q_QDOC)
298 CGImageRef toCGImage() const Q_DECL_CF_RETURNS_RETAINED;
299#endif
300#if defined(Q_OS_WIN) || defined(Q_QDOC)
301 HBITMAP toHBITMAP() const;
302 HICON toHICON(const QImage &mask = {}) const;
303 static QImage fromHBITMAP(HBITMAP hbitmap);
304 static QImage fromHICON(HICON icon);
305#endif
306
307protected:
308 virtual int metric(PaintDeviceMetric metric) const override;
309 QImage mirrored_helper(bool horizontal, bool vertical) const;
310 QImage rgbSwapped_helper() const;
311 void mirrored_inplace(bool horizontal, bool vertical);
312 void rgbSwapped_inplace();
313 QImage convertToFormat_helper(Format format, Qt::ImageConversionFlags flags) const;
314 bool convertToFormat_inplace(Format format, Qt::ImageConversionFlags flags);
315 QImage smoothScaled(int w, int h) const;
316
317 void detachMetadata(bool invalidateCache = false);
318
319private:
320 QImageData *d;
321
322 friend class QRasterPlatformPixmap;
323 friend class QBlittablePlatformPixmap;
324 friend class QPixmapCacheEntry;
325 friend struct QImageData;
326
327public:
328 typedef QImageData * DataPtr;
329 inline DataPtr &data_ptr() { return d; }
330};
331
332Q_DECLARE_SHARED(QImage)
333
334// Inline functions...
335
336inline bool QImage::valid(const QPoint &pt) const { return valid(pt.x(), pt.y()); }
337inline int QImage::pixelIndex(const QPoint &pt) const { return pixelIndex(pt.x(), pt.y());}
338inline QRgb QImage::pixel(const QPoint &pt) const { return pixel(pt.x(), pt.y()); }
339inline void QImage::setPixel(const QPoint &pt, uint index_or_rgb) { setPixel(pt.x(), pt.y(), index_or_rgb); }
340inline QColor QImage::pixelColor(const QPoint &pt) const { return pixelColor(pt.x(), pt.y()); }
341inline void QImage::setPixelColor(const QPoint &pt, const QColor &c) { setPixelColor(pt.x(), pt.y(), c); }
342
343// QImage stream functions
344
345#if !defined(QT_NO_DATASTREAM)
346Q_GUI_EXPORT QDataStream &operator<<(QDataStream &, const QImage &);
347Q_GUI_EXPORT QDataStream &operator>>(QDataStream &, QImage &);
348#endif
349
350#ifndef QT_NO_DEBUG_STREAM
351Q_GUI_EXPORT QDebug operator<<(QDebug, const QImage &);
352#endif
353
354
355QT_END_NAMESPACE
356
357#endif // QIMAGE_H
QBitmap
\inmodule QtGui
Definition qbitmap.h:17
QColorTransform
The QColorTransform class is a transformation between color spaces.
Definition qcolortransform.h:27
QDataStream
\inmodule QtCore\reentrant
Definition qdatastream.h:50
QImage
\inmodule QtGui
Definition qimage.h:38
QT_BEGIN_NAMESPACE
Combined button and popup list for selecting options.
Definition qrandomaccessasyncfile_darwin.mm:17
makeBitmap
static QBitmap makeBitmap(QImage &&image, Qt::ImageConversionFlags flags)
Definition qbitmap.cpp:142
operator<<
Q_CORE_EXPORT QDebug operator<<(QDebug debug, QDir::Filters filters)
Definition qdir.cpp:2582
QImageCleanupFunction
void(* QImageCleanupFunction)(void *)
Definition qimage.h:35