include/QtGui/qimage.h

0001 // Copyright (C) 2021 The Qt Company Ltd.
0002 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
0003
0004 #ifndef QIMAGE_H
0005 #define QIMAGE_H
0006
0007 #include <QtGui/qtguiglobal.h>
0008 #include <QtGui/qcolor.h>
0009 #include <QtGui/qrgb.h>
0010 #include <QtGui/qpaintdevice.h>
0011 #include <QtGui/qpixelformat.h>
0012 #include <QtGui/qtransform.h>
0013 #include <QtCore/qbytearray.h>
0014 #include <QtCore/qbytearrayview.h>
0015 #include <QtCore/qrect.h>
0016 #include <QtCore/qstring.h>
0017 #include <QtCore/qcontainerfwd.h>
0018
0019 #if defined(Q_OS_DARWIN) || defined(Q_QDOC)
0020 Q_FORWARD_DECLARE_MUTABLE_CG_TYPE(CGImage);
0021 #endif
0022
0023 QT_BEGIN_NAMESPACE
0024
0025
0026 class QColorSpace;
0027 class QColorTransform;
0028 class QIODevice;
0029 class QTransform;
0030 class QVariant;
0031
0032 struct QImageData;
0033
0034 typedef void (*QImageCleanupFunction)(void*);
0035
0036 class Q_GUI_EXPORT QImage : public QPaintDevice
0037 {
0038     Q_GADGET
0039 public:
0040     enum InvertMode { InvertRgb, InvertRgba };
0041     enum Format {
0042         Format_Invalid,
0043         Format_Mono,
0044         Format_MonoLSB,
0045         Format_Indexed8,
0046         Format_RGB32,
0047         Format_ARGB32,
0048         Format_ARGB32_Premultiplied,
0049         Format_RGB16,
0050         Format_ARGB8565_Premultiplied,
0051         Format_RGB666,
0052         Format_ARGB6666_Premultiplied,
0053         Format_RGB555,
0054         Format_ARGB8555_Premultiplied,
0055         Format_RGB888,
0056         Format_RGB444,
0057         Format_ARGB4444_Premultiplied,
0058         Format_RGBX8888,
0059         Format_RGBA8888,
0060         Format_RGBA8888_Premultiplied,
0061         Format_BGR30,
0062         Format_A2BGR30_Premultiplied,
0063         Format_RGB30,
0064         Format_A2RGB30_Premultiplied,
0065         Format_Alpha8,
0066         Format_Grayscale8,
0067         Format_RGBX64,
0068         Format_RGBA64,
0069         Format_RGBA64_Premultiplied,
0070         Format_Grayscale16,
0071         Format_BGR888,
0072         Format_RGBX16FPx4,
0073         Format_RGBA16FPx4,
0074         Format_RGBA16FPx4_Premultiplied,
0075         Format_RGBX32FPx4,
0076         Format_RGBA32FPx4,
0077         Format_RGBA32FPx4_Premultiplied,
0078         Format_CMYK8888,
0079 #ifndef Q_QDOC
0080         NImageFormats
0081 #endif
0082     };
0083     Q_ENUM(Format)
0084
0085     QImage() noexcept;
0086     QImage(const QSize &size, Format format);
0087     QImage(int width, int height, Format format);
0088     QImage(uchar *data, int width, int height, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
0089     QImage(const uchar *data, int width, int height, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
0090     QImage(uchar *data, int width, int height, qsizetype bytesPerLine, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
0091     QImage(const uchar *data, int width, int height, qsizetype bytesPerLine, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
0092
0093 #ifndef QT_NO_IMAGEFORMAT_XPM
0094     explicit QImage(const char * const xpm[]);
0095 #endif
0096     explicit QImage(const QString &fileName, const char *format = nullptr);
0097
0098     QImage(const QImage &);
0099     QImage(QImage &&other) noexcept
0100         : QPaintDevice(), d(std::exchange(other.d, nullptr))
0101     {}
0102     ~QImage();
0103
0104     QImage &operator=(const QImage &);
0105     QT_MOVE_ASSIGNMENT_OPERATOR_IMPL_VIA_MOVE_AND_SWAP(QImage)
0106     void swap(QImage &other) noexcept
0107     { qt_ptr_swap(d, other.d); }
0108
0109     bool isNull() const;
0110
0111     int devType() const override;
0112
0113     bool operator==(const QImage &) const;
0114     bool operator!=(const QImage &) const;
0115     operator QVariant() const;
0116     void detach();
0117     bool isDetached() const;
0118
0119     [[nodiscard]] QImage copy(const QRect &rect = QRect()) const;
0120     [[nodiscard]] QImage copy(int x, int y, int w, int h) const
0121     { return copy(QRect(x, y, w, h)); }
0122
0123     Format format() const;
0124
0125     [[nodiscard]] QImage convertToFormat(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) const &
0126     { return convertToFormat_helper(f, flags); }
0127     [[nodiscard]] QImage convertToFormat(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) &&
0128     {
0129         if (convertToFormat_inplace(f, flags))
0130             return std::move(*this);
0131         else
0132             return convertToFormat_helper(f, flags);
0133     }
0134     [[nodiscard]] QImage convertToFormat(Format f, const QList<QRgb> &colorTable,
0135                                          Qt::ImageConversionFlags flags = Qt::AutoColor) const;
0136
0137     bool reinterpretAsFormat(Format f);
0138     [[nodiscard]] QImage convertedTo(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) const &
0139     { return convertToFormat(f, flags); }
0140     [[nodiscard]] QImage convertedTo(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) &&
0141     { return convertToFormat(f, flags); }
0142     void convertTo(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor);
0143
0144     int width() const;
0145     int height() const;
0146     QSize size() const;
0147     QRect rect() const;
0148
0149     int depth() const;
0150     int colorCount() const;
0151     int bitPlaneCount() const;
0152
0153     QRgb color(int i) const;
0154     void setColor(int i, QRgb c);
0155     void setColorCount(int);
0156
0157     bool allGray() const;
0158     bool isGrayscale() const;
0159
0160     uchar *bits();
0161     const uchar *bits() const;
0162     const uchar *constBits() const;
0163
0164     qsizetype sizeInBytes() const;
0165
0166     uchar *scanLine(int);
0167     const uchar *scanLine(int) const;
0168     const uchar *constScanLine(int) const;
0169     qsizetype bytesPerLine() const;
0170
0171     bool valid(int x, int y) const;
0172     bool valid(const QPoint &pt) const;
0173
0174     int pixelIndex(int x, int y) const;
0175     int pixelIndex(const QPoint &pt) const;
0176
0177     QRgb pixel(int x, int y) const;
0178     QRgb pixel(const QPoint &pt) const;
0179
0180     void setPixel(int x, int y, uint index_or_rgb);
0181     void setPixel(const QPoint &pt, uint index_or_rgb);
0182
0183     QColor pixelColor(int x, int y) const;
0184     QColor pixelColor(const QPoint &pt) const;
0185
0186     void setPixelColor(int x, int y, const QColor &c);
0187     void setPixelColor(const QPoint &pt, const QColor &c);
0188
0189     QList<QRgb> colorTable() const;
0190     void setColorTable(const QList<QRgb> &colors);
0191
0192     qreal devicePixelRatio() const;
0193     void setDevicePixelRatio(qreal scaleFactor);
0194     QSizeF deviceIndependentSize() const;
0195
0196     void fill(uint pixel);
0197     void fill(const QColor &color);
0198     void fill(Qt::GlobalColor color);
0199
0200
0201     bool hasAlphaChannel() const;
0202     void setAlphaChannel(const QImage &alphaChannel);
0203     [[nodiscard]] QImage createAlphaMask(Qt::ImageConversionFlags flags = Qt::AutoColor) const;
0204 #ifndef QT_NO_IMAGE_HEURISTIC_MASK
0205     [[nodiscard]] QImage createHeuristicMask(bool clipTight = true) const;
0206 #endif
0207     [[nodiscard]] QImage createMaskFromColor(QRgb color, Qt::MaskMode mode = Qt::MaskInColor) const;
0208
0209     [[nodiscard]] QImage scaled(int w, int h, Qt::AspectRatioMode aspectMode = Qt::IgnoreAspectRatio,
0210                                 Qt::TransformationMode mode = Qt::FastTransformation) const
0211     { return scaled(QSize(w, h), aspectMode, mode); }
0212     [[nodiscard]] QImage scaled(const QSize &s, Qt::AspectRatioMode aspectMode = Qt::IgnoreAspectRatio,
0213                                 Qt::TransformationMode mode = Qt::FastTransformation) const;
0214     [[nodiscard]] QImage scaledToWidth(int w, Qt::TransformationMode mode = Qt::FastTransformation) const;
0215     [[nodiscard]] QImage scaledToHeight(int h, Qt::TransformationMode mode = Qt::FastTransformation) const;
0216     [[nodiscard]] QImage transformed(const QTransform &matrix, Qt::TransformationMode mode = Qt::FastTransformation) const;
0217     static QTransform trueMatrix(const QTransform &, int w, int h);
0218 #if QT_DEPRECATED_SINCE(6, 13)
0219     QT_DEPRECATED_VERSION_X_6_13("Use flipped(Qt::Orientations) instead")
0220     [[nodiscard]] QImage mirrored(bool horizontally = false, bool vertically = true) const &
0221     { return mirrored_helper(horizontally, vertically); }
0222     QT_DEPRECATED_VERSION_X_6_13("Use flipped(Qt::Orientations) instead")
0223     [[nodiscard]] QImage mirrored(bool horizontally = false, bool vertically = true) &&
0224     { mirrored_inplace(horizontally, vertically); return std::move(*this); }
0225     QT_DEPRECATED_VERSION_X_6_13("Use flip(Qt::Orientations) instead")
0226     void mirror(bool horizontally = false, bool vertically = true)
0227     { mirrored_inplace(horizontally, vertically); }
0228 #endif
0229     [[nodiscard]] QImage rgbSwapped() const &
0230     { return rgbSwapped_helper(); }
0231     [[nodiscard]] QImage rgbSwapped() &&
0232     { rgbSwapped_inplace(); return std::move(*this); }
0233     [[nodiscard]] QImage flipped(Qt::Orientations orient = Qt::Vertical) const &
0234     { return mirrored_helper(orient.testFlag(Qt::Horizontal), orient.testFlag(Qt::Vertical)); }
0235     [[nodiscard]] QImage flipped(Qt::Orientations orient = Qt::Vertical) &&
0236     { mirrored_inplace(orient.testFlag(Qt::Horizontal), orient.testFlag(Qt::Vertical)); return std::move(*this); }
0237     void flip(Qt::Orientations orient = Qt::Vertical)
0238     { mirrored_inplace(orient.testFlag(Qt::Horizontal), orient.testFlag(Qt::Vertical)); }
0239     void rgbSwap()
0240     { rgbSwapped_inplace(); }
0241     void invertPixels(InvertMode = InvertRgb);
0242
0243     QColorSpace colorSpace() const;
0244     [[nodiscard]] QImage convertedToColorSpace(const QColorSpace &colorSpace) const;
0245     [[nodiscard]] QImage convertedToColorSpace(const QColorSpace &colorSpace, QImage::Format format,
0246                                                Qt::ImageConversionFlags flags = Qt::AutoColor) const &;
0247     [[nodiscard]] QImage convertedToColorSpace(const QColorSpace &colorSpace, QImage::Format format,
0248                                                Qt::ImageConversionFlags flags = Qt::AutoColor) &&;
0249     void convertToColorSpace(const QColorSpace &colorSpace);
0250     void convertToColorSpace(const QColorSpace &colorSpace, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor);
0251     void setColorSpace(const QColorSpace &colorSpace);
0252
0253     QImage colorTransformed(const QColorTransform &transform) const &;
0254     QImage colorTransformed(const QColorTransform &transform, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) const &;
0255     QImage colorTransformed(const QColorTransform &transform) &&;
0256     QImage colorTransformed(const QColorTransform &transform, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) &&;
0257     void applyColorTransform(const QColorTransform &transform);
0258     void applyColorTransform(const QColorTransform &transform, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor);
0259
0260     bool load(QIODevice *device, const char *format);
0261     bool load(const QString &fileName, const char *format = nullptr);
0262     bool loadFromData(QByteArrayView data, const char *format = nullptr);
0263     bool loadFromData(const uchar *buf, int len, const char *format = nullptr); // ### Qt 7: qsizetype
0264     bool loadFromData(const QByteArray &data, const char *format = nullptr) // ### Qt 7: drop
0265     { return loadFromData(QByteArrayView(data), format); }
0266
0267     bool save(const QString &fileName, const char *format = nullptr, int quality = -1) const;
0268     bool save(QIODevice *device, const char *format = nullptr, int quality = -1) const;
0269
0270     static QImage fromData(QByteArrayView data, const char *format = nullptr);
0271     static QImage fromData(const uchar *data, int size, const char *format = nullptr); // ### Qt 7: qsizetype
0272     static QImage fromData(const QByteArray &data, const char *format = nullptr)  // ### Qt 7: drop
0273     { return fromData(QByteArrayView(data), format); }
0274
0275     qint64 cacheKey() const;
0276
0277     QPaintEngine *paintEngine() const override;
0278
0279     // Auxiliary data
0280     int dotsPerMeterX() const;
0281     int dotsPerMeterY() const;
0282     void setDotsPerMeterX(int);
0283     void setDotsPerMeterY(int);
0284     QPoint offset() const;
0285     void setOffset(const QPoint&);
0286
0287     QStringList textKeys() const;
0288     QString text(const QString &key = QString()) const;
0289     void setText(const QString &key, const QString &value);
0290
0291     QPixelFormat pixelFormat() const noexcept;
0292     static QPixelFormat toPixelFormat(QImage::Format format) noexcept;
0293     static QImage::Format toImageFormat(QPixelFormat format) noexcept;
0294
0295     // Platform specific conversion functions
0296 #if defined(Q_OS_DARWIN) || defined(Q_QDOC)
0297     CGImageRef toCGImage() const Q_DECL_CF_RETURNS_RETAINED;
0298 #endif
0299 #if defined(Q_OS_WIN) || defined(Q_QDOC)
0300     HBITMAP toHBITMAP() const;
0301     HICON toHICON(const QImage &mask = {}) const;
0302     static QImage fromHBITMAP(HBITMAP hbitmap);
0303     static QImage fromHICON(HICON icon);
0304 #endif
0305
0306 protected:
0307     virtual int metric(PaintDeviceMetric metric) const override;
0308     QImage mirrored_helper(bool horizontal, bool vertical) const;
0309     QImage rgbSwapped_helper() const;
0310     void mirrored_inplace(bool horizontal, bool vertical);
0311     void rgbSwapped_inplace();
0312     QImage convertToFormat_helper(Format format, Qt::ImageConversionFlags flags) const;
0313     bool convertToFormat_inplace(Format format, Qt::ImageConversionFlags flags);
0314     QImage smoothScaled(int w, int h) const;
0315
0316     void detachMetadata(bool invalidateCache = false);
0317
0318 private:
0319     QImageData *d;
0320
0321     friend class QRasterPlatformPixmap;
0322     friend class QBlittablePlatformPixmap;
0323     friend class QPixmapCacheEntry;
0324     friend struct QImageData;
0325
0326 public:
0327     typedef QImageData * DataPtr;
0328     inline DataPtr &data_ptr() { return d; }
0329 };
0330
0331 Q_DECLARE_SHARED(QImage)
0332
0333 // Inline functions...
0334
0335 inline bool QImage::valid(const QPoint &pt) const { return valid(pt.x(), pt.y()); }
0336 inline int QImage::pixelIndex(const QPoint &pt) const { return pixelIndex(pt.x(), pt.y());}
0337 inline QRgb QImage::pixel(const QPoint &pt) const { return pixel(pt.x(), pt.y()); }
0338 inline void QImage::setPixel(const QPoint &pt, uint index_or_rgb) { setPixel(pt.x(), pt.y(), index_or_rgb); }
0339 inline QColor QImage::pixelColor(const QPoint &pt) const { return pixelColor(pt.x(), pt.y()); }
0340 inline void QImage::setPixelColor(const QPoint &pt, const QColor &c) { setPixelColor(pt.x(), pt.y(), c); }
0341
0342 // QImage stream functions
0343
0344 #if !defined(QT_NO_DATASTREAM)
0345 Q_GUI_EXPORT QDataStream &operator<<(QDataStream &, const QImage &);
0346 Q_GUI_EXPORT QDataStream &operator>>(QDataStream &, QImage &);
0347 #endif
0348
0349 #ifndef QT_NO_DEBUG_STREAM
0350 Q_GUI_EXPORT QDebug operator<<(QDebug, const QImage &);
0351 #endif
0352
0353
0354 QT_END_NAMESPACE
0355
0356 #endif // QIMAGE_H