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 #ifndef Q_QDOC
0079         NImageFormats
0080 #endif
0081     };
0082     Q_ENUM(Format)
0083
0084     QImage() noexcept;
0085     QImage(const QSize &size, Format format);
0086     QImage(int width, int height, Format format);
0087     QImage(uchar *data, int width, int height, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
0088     QImage(const uchar *data, int width, int height, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
0089     QImage(uchar *data, int width, int height, qsizetype bytesPerLine, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
0090     QImage(const uchar *data, int width, int height, qsizetype bytesPerLine, Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr);
0091
0092 #ifndef QT_NO_IMAGEFORMAT_XPM
0093     explicit QImage(const char * const xpm[]);
0094 #endif
0095     explicit QImage(const QString &fileName, const char *format = nullptr);
0096
0097     QImage(const QImage &);
0098     QImage(QImage &&other) noexcept
0099         : QPaintDevice(), d(std::exchange(other.d, nullptr))
0100     {}
0101     ~QImage();
0102
0103     QImage &operator=(const QImage &);
0104     QT_MOVE_ASSIGNMENT_OPERATOR_IMPL_VIA_MOVE_AND_SWAP(QImage)
0105     void swap(QImage &other) noexcept
0106     { qt_ptr_swap(d, other.d); }
0107
0108     bool isNull() const;
0109
0110     int devType() const override;
0111
0112     bool operator==(const QImage &) const;
0113     bool operator!=(const QImage &) const;
0114     operator QVariant() const;
0115     void detach();
0116     bool isDetached() const;
0117
0118     [[nodiscard]] QImage copy(const QRect &rect = QRect()) const;
0119     [[nodiscard]] QImage copy(int x, int y, int w, int h) const
0120     { return copy(QRect(x, y, w, h)); }
0121
0122     Format format() const;
0123
0124     [[nodiscard]] QImage convertToFormat(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) const &
0125     { return convertToFormat_helper(f, flags); }
0126     [[nodiscard]] QImage convertToFormat(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) &&
0127     {
0128         if (convertToFormat_inplace(f, flags))
0129             return std::move(*this);
0130         else
0131             return convertToFormat_helper(f, flags);
0132     }
0133     [[nodiscard]] QImage convertToFormat(Format f, const QList<QRgb> &colorTable,
0134                                          Qt::ImageConversionFlags flags = Qt::AutoColor) const;
0135
0136     bool reinterpretAsFormat(Format f);
0137     [[nodiscard]] QImage convertedTo(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) const &
0138     { return convertToFormat(f, flags); }
0139     [[nodiscard]] QImage convertedTo(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) &&
0140     { return convertToFormat(f, flags); }
0141     void convertTo(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor);
0142
0143     int width() const;
0144     int height() const;
0145     QSize size() const;
0146     QRect rect() const;
0147
0148     int depth() const;
0149     int colorCount() const;
0150     int bitPlaneCount() const;
0151
0152     QRgb color(int i) const;
0153     void setColor(int i, QRgb c);
0154     void setColorCount(int);
0155
0156     bool allGray() const;
0157     bool isGrayscale() const;
0158
0159     uchar *bits();
0160     const uchar *bits() const;
0161     const uchar *constBits() const;
0162
0163     qsizetype sizeInBytes() const;
0164
0165     uchar *scanLine(int);
0166     const uchar *scanLine(int) const;
0167     const uchar *constScanLine(int) const;
0168     qsizetype bytesPerLine() const;
0169
0170     bool valid(int x, int y) const;
0171     bool valid(const QPoint &pt) const;
0172
0173     int pixelIndex(int x, int y) const;
0174     int pixelIndex(const QPoint &pt) const;
0175
0176     QRgb pixel(int x, int y) const;
0177     QRgb pixel(const QPoint &pt) const;
0178
0179     void setPixel(int x, int y, uint index_or_rgb);
0180     void setPixel(const QPoint &pt, uint index_or_rgb);
0181
0182     QColor pixelColor(int x, int y) const;
0183     QColor pixelColor(const QPoint &pt) const;
0184
0185     void setPixelColor(int x, int y, const QColor &c);
0186     void setPixelColor(const QPoint &pt, const QColor &c);
0187
0188     QList<QRgb> colorTable() const;
0189     void setColorTable(const QList<QRgb> &colors);
0190
0191     qreal devicePixelRatio() const;
0192     void setDevicePixelRatio(qreal scaleFactor);
0193     QSizeF deviceIndependentSize() const;
0194
0195     void fill(uint pixel);
0196     void fill(const QColor &color);
0197     void fill(Qt::GlobalColor color);
0198
0199
0200     bool hasAlphaChannel() const;
0201     void setAlphaChannel(const QImage &alphaChannel);
0202     [[nodiscard]] QImage createAlphaMask(Qt::ImageConversionFlags flags = Qt::AutoColor) const;
0203 #ifndef QT_NO_IMAGE_HEURISTIC_MASK
0204     [[nodiscard]] QImage createHeuristicMask(bool clipTight = true) const;
0205 #endif
0206     [[nodiscard]] QImage createMaskFromColor(QRgb color, Qt::MaskMode mode = Qt::MaskInColor) const;
0207
0208     [[nodiscard]] QImage scaled(int w, int h, Qt::AspectRatioMode aspectMode = Qt::IgnoreAspectRatio,
0209                                 Qt::TransformationMode mode = Qt::FastTransformation) const
0210     { return scaled(QSize(w, h), aspectMode, mode); }
0211     [[nodiscard]] QImage scaled(const QSize &s, Qt::AspectRatioMode aspectMode = Qt::IgnoreAspectRatio,
0212                                 Qt::TransformationMode mode = Qt::FastTransformation) const;
0213     [[nodiscard]] QImage scaledToWidth(int w, Qt::TransformationMode mode = Qt::FastTransformation) const;
0214     [[nodiscard]] QImage scaledToHeight(int h, Qt::TransformationMode mode = Qt::FastTransformation) const;
0215     [[nodiscard]] QImage transformed(const QTransform &matrix, Qt::TransformationMode mode = Qt::FastTransformation) const;
0216     static QTransform trueMatrix(const QTransform &, int w, int h);
0217
0218     [[nodiscard]] QImage mirrored(bool horizontally = false, bool vertically = true) const &
0219     { return mirrored_helper(horizontally, vertically); }
0220     [[nodiscard]] QImage mirrored(bool horizontally = false, bool vertically = true) &&
0221     { mirrored_inplace(horizontally, vertically); return std::move(*this); }
0222     [[nodiscard]] QImage rgbSwapped() const &
0223     { return rgbSwapped_helper(); }
0224     [[nodiscard]] QImage rgbSwapped() &&
0225     { rgbSwapped_inplace(); return std::move(*this); }
0226     void mirror(bool horizontally = false, bool vertically = true)
0227     { mirrored_inplace(horizontally, vertically); }
0228     void rgbSwap()
0229     { rgbSwapped_inplace(); }
0230     void invertPixels(InvertMode = InvertRgb);
0231
0232     QColorSpace colorSpace() const;
0233     [[nodiscard]] QImage convertedToColorSpace(const QColorSpace &) const;
0234     void convertToColorSpace(const QColorSpace &);
0235     void setColorSpace(const QColorSpace &);
0236
0237     QImage colorTransformed(const QColorTransform &transform) const &;
0238     QImage colorTransformed(const QColorTransform &transform) &&;
0239     void applyColorTransform(const QColorTransform &transform);
0240
0241     bool load(QIODevice *device, const char *format);
0242     bool load(const QString &fileName, const char *format = nullptr);
0243     bool loadFromData(QByteArrayView data, const char *format = nullptr);
0244     bool loadFromData(const uchar *buf, int len, const char *format = nullptr); // ### Qt 7: qsizetype
0245     bool loadFromData(const QByteArray &data, const char *format = nullptr) // ### Qt 7: drop
0246     { return loadFromData(QByteArrayView(data), format); }
0247
0248     bool save(const QString &fileName, const char *format = nullptr, int quality = -1) const;
0249     bool save(QIODevice *device, const char *format = nullptr, int quality = -1) const;
0250
0251     static QImage fromData(QByteArrayView data, const char *format = nullptr);
0252     static QImage fromData(const uchar *data, int size, const char *format = nullptr); // ### Qt 7: qsizetype
0253     static QImage fromData(const QByteArray &data, const char *format = nullptr)  // ### Qt 7: drop
0254     { return fromData(QByteArrayView(data), format); }
0255
0256     qint64 cacheKey() const;
0257
0258     QPaintEngine *paintEngine() const override;
0259
0260     // Auxiliary data
0261     int dotsPerMeterX() const;
0262     int dotsPerMeterY() const;
0263     void setDotsPerMeterX(int);
0264     void setDotsPerMeterY(int);
0265     QPoint offset() const;
0266     void setOffset(const QPoint&);
0267
0268     QStringList textKeys() const;
0269     QString text(const QString &key = QString()) const;
0270     void setText(const QString &key, const QString &value);
0271
0272     QPixelFormat pixelFormat() const noexcept;
0273     static QPixelFormat toPixelFormat(QImage::Format format) noexcept;
0274     static QImage::Format toImageFormat(QPixelFormat format) noexcept;
0275
0276     // Platform specific conversion functions
0277 #if defined(Q_OS_DARWIN) || defined(Q_QDOC)
0278     CGImageRef toCGImage() const Q_DECL_CF_RETURNS_RETAINED;
0279 #endif
0280 #if defined(Q_OS_WIN) || defined(Q_QDOC)
0281     HBITMAP toHBITMAP() const;
0282     HICON toHICON(const QImage &mask = {}) const;
0283     static QImage fromHBITMAP(HBITMAP hbitmap);
0284     static QImage fromHICON(HICON icon);
0285 #endif
0286
0287 protected:
0288     virtual int metric(PaintDeviceMetric metric) const override;
0289     QImage mirrored_helper(bool horizontal, bool vertical) const;
0290     QImage rgbSwapped_helper() const;
0291     void mirrored_inplace(bool horizontal, bool vertical);
0292     void rgbSwapped_inplace();
0293     QImage convertToFormat_helper(Format format, Qt::ImageConversionFlags flags) const;
0294     bool convertToFormat_inplace(Format format, Qt::ImageConversionFlags flags);
0295     QImage smoothScaled(int w, int h) const;
0296
0297     void detachMetadata(bool invalidateCache = false);
0298
0299 private:
0300     QImageData *d;
0301
0302     friend class QRasterPlatformPixmap;
0303     friend class QBlittablePlatformPixmap;
0304     friend class QPixmapCacheEntry;
0305     friend struct QImageData;
0306
0307 public:
0308     typedef QImageData * DataPtr;
0309     inline DataPtr &data_ptr() { return d; }
0310 };
0311
0312 Q_DECLARE_SHARED(QImage)
0313
0314 // Inline functions...
0315
0316 inline bool QImage::valid(const QPoint &pt) const { return valid(pt.x(), pt.y()); }
0317 inline int QImage::pixelIndex(const QPoint &pt) const { return pixelIndex(pt.x(), pt.y());}
0318 inline QRgb QImage::pixel(const QPoint &pt) const { return pixel(pt.x(), pt.y()); }
0319 inline void QImage::setPixel(const QPoint &pt, uint index_or_rgb) { setPixel(pt.x(), pt.y(), index_or_rgb); }
0320 inline QColor QImage::pixelColor(const QPoint &pt) const { return pixelColor(pt.x(), pt.y()); }
0321 inline void QImage::setPixelColor(const QPoint &pt, const QColor &c) { setPixelColor(pt.x(), pt.y(), c); }
0322
0323 // QImage stream functions
0324
0325 #if !defined(QT_NO_DATASTREAM)
0326 Q_GUI_EXPORT QDataStream &operator<<(QDataStream &, const QImage &);
0327 Q_GUI_EXPORT QDataStream &operator>>(QDataStream &, QImage &);
0328 #endif
0329
0330 #ifndef QT_NO_DEBUG_STREAM
0331 Q_GUI_EXPORT QDebug operator<<(QDebug, const QImage &);
0332 #endif
0333
0334
0335 QT_END_NAMESPACE
0336
0337 #endif // QIMAGE_H