QImage Class

成员函数文档

返回给定format 中的图像副本。

指定的图像转换flags 控制转换过程中图像数据的处理方式。

另请参阅 convertTo() 和Image Formats 。

返回给定format 中的图像副本。

指定的图像转换flags 控制转换过程中图像数据的处理方式。

此函数在 Qt 6.0 中引入。

另请参阅 convertTo() 和Image Formats 。

根据horizontal 和vertical 设置为 true 或 false，返回图像的水平和/或垂直方向镜像。

请注意，原始图像不会改变。

另请参阅 mirror() 和Image Transformations 。

返回一个QImage ，其中所有像素的红色和蓝色分量值均已交换，从而有效地将 RGB 图像转换为 BGR 图像。

原始QImage 不会改变。

另请参阅 rgbSwap() 和Image Transformations 。

返回转换为colorSpace 和format 的图像。

如果图像没有有效的色彩空间，则返回空QImage 。

指定的图像转换flags 控制在格式转换过程中如何处理图像数据。

此函数在 Qt 6.8 中引入。

另请参阅 colorTransformed() 。

[noexcept] QImage::QImage()

构造一个空图像。

另请参见 isNull()。

[explicit] QImage::QImage(const char *const[] xpm)

根据给定的xpm 图像构建图像。

确保图像是有效的 XPM 图像。错误将被忽略。

请注意，通过使用不同寻常的声明，可以稍微压缩 XPM 变量：

static const char * const start_xpm[] = {
    "16 15 8 1",
    "a c #cec6bd",
    // etc.
};

额外的const 使整个定义为只读，这样效率稍高（例如，当代码位于共享库中时），并能与应用程序一起存储在 ROM 中。

QImage::QImage(const QSize &size, QImage::Format format)

用给定的size 和format 构建图像。

如果无法分配内存，则返回null 图像。

[explicit] QImage::QImage(const QString &fileName, const char *format = nullptr)

构建图像并尝试从文件中加载图像，文件名为fileName 。

加载器会尝试使用指定的format 读取图像。如果未指定format （默认情况），则会根据文件后缀和文件头自动检测。详情请参阅 {QImageReader::setAutoDetectImageFormat()}{QImageReader}。

如果图像加载失败，此对象将是一个空图像。

文件名既可以指磁盘上的实际文件，也可以指应用程序的嵌入式资源。有关如何在应用程序的可执行文件中嵌入图片和其他资源文件的详细信息，请参阅资源系统概述。

另请参阅 isNull() 和Reading and Writing Image Files 。

QImage::QImage(int width, int height, QImage::Format format)

使用给定的width 、height 和format 构建图像。

如果无法分配内存，将返回null 图像。

QImage::QImage(const uchar *data, int width, int height, QImage::Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr)

使用给定的width 、height 和format 构建图像，该图像使用现有的只读内存缓冲区data 。width 和height 必须以像素为单位指定，data 必须是 32 位对齐，图像中的每个数据扫描线也必须是 32 位对齐。

缓冲区必须在 QImage 和所有未修改或未从原始缓冲区分离的副本的整个生命周期内保持有效。图像销毁时不会删除缓冲区。您可以提供一个函数指针cleanupFunction 以及一个额外的指针cleanupInfo ，该指针将在最后一个副本销毁时被调用。

如果format 是索引颜色格式，那么图像颜色表最初是空的，必须在使用图像前用setColorCount() 或setColorTable() 充分扩展。

类似的 QImage 构造函数会获取一个非常数数据缓冲区，与之不同的是，该版本永远不会更改缓冲区的内容。例如，调用QImage::bits() 将返回图像的深度副本，而不是传给构造函数的缓冲区。这使得从原始数据构建 QImage 更有效率，而不会改变原始数据。

QImage::QImage(uchar *data, int width, int height, QImage::Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr)

使用给定的width 、height 和format 构建图像，该图像使用现有的内存缓冲区data 。width 和height 必须以像素为单位指定，data 必须是 32 位对齐，图像中的每个数据扫描线也必须是 32 位对齐。

缓冲区必须在 QImage 和所有未修改或未从原始缓冲区分离的副本的整个生命周期内保持有效。图像销毁时不会删除缓冲区。您可以提供一个函数指针cleanupFunction 以及一个额外的指针cleanupInfo ，该指针将在最后一个副本销毁时被调用。

如果format 是索引颜色格式，图像颜色表最初是空的，必须在使用图像前用setColorCount() 或setColorTable() 充分扩展。

QImage::QImage(const uchar *data, int width, int height, qsizetype bytesPerLine, QImage::Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr)

使用给定的width 、height 和format 构建图像，该图像使用现有的内存缓冲区data 。width 和height 必须以像素为单位指定。bytesPerLine 指定每行的字节数（stride）。

缓冲区必须在 QImage 和所有未修改或未从原始缓冲区分离的副本的整个生命周期内保持有效。图像销毁时不会删除缓冲区。您可以提供一个函数指针cleanupFunction 以及一个额外的指针cleanupInfo ，该指针将在最后一个副本销毁时被调用。

如果format 是索引颜色格式，那么图像颜色表最初是空的，必须在使用图像前用setColorCount() 或setColorTable() 充分扩展。

类似的 QImage 构造函数会获取一个非常数数据缓冲区，与之不同的是，该版本永远不会更改缓冲区的内容。例如，调用QImage::bits() 将返回图像的深度副本，而不是传给构造函数的缓冲区。这使得从原始数据构建 QImage 更有效率，而不会改变原始数据。

QImage::QImage(uchar *data, int width, int height, qsizetype bytesPerLine, QImage::Format format, QImageCleanupFunction cleanupFunction = nullptr, void *cleanupInfo = nullptr)

使用给定的width 、height 和format 构建图像，该图像使用现有的内存缓冲区data 。width 和height 必须以像素为单位指定。bytesPerLine 指定每行的字节数（stride）。

缓冲区必须在 QImage 和所有未修改或未从原始缓冲区分离的副本的整个生命周期内保持有效。图像销毁时不会删除缓冲区。您可以提供一个函数指针cleanupFunction 以及一个额外的指针cleanupInfo ，该指针将在最后一个副本销毁时被调用。

如果format 是索引颜色格式，图像颜色表最初是空的，必须在使用图像前用setColorCount() 或setColorTable() 充分扩展。

QImage::QImage(const QImage &image)

构建给定image 的浅层副本。

有关浅层副本的更多信息，请参阅隐式数据共享文档。

另请参阅 copy()。

[noexcept] QImage::QImage(QImage &&other)

Move-构建一个 QImage 实例，使其指向other 所指向的同一对象。

[virtual noexcept] QImage::~QImage()

销毁图像并清理。

bool QImage::allGray() const

如果图像中的所有颜色都是灰色阴影（即红、绿、蓝三色分量相等），则返回true ；否则返回 false。

请注意，对于没有颜色表的图像，此函数的运行速度较慢。

另请参见 isGrayscale()。

void QImage::applyColorTransform(const QColorTransform &transform)

对图像中的所有像素应用颜色变换transform 。

[since 6.8] void QImage::applyColorTransform(const QColorTransform &transform, QImage::Format toFormat, Qt::ImageConversionFlags flags = Qt::AutoColor)

对图像中的所有像素应用颜色转换transform ，并将图像格式转换为toFormat 。

指定的图像转换flags 可控制在格式转换过程中如何处理图像数据。

此函数在 Qt 6.8 中引入。

int QImage::bitPlaneCount() const

返回图像的位平面数。

位平面数是指每个像素的颜色和透明度信息的位数。当图像格式包含未使用位时，位平面数不同于深度（即小于深度）。

另请参阅 depth()、format() 和Image Formats 。

uchar *QImage::bits()

返回指向第一个像素数据的指针。这相当于scanLine(0)。

请注意，QImage 使用隐式数据共享。此函数会对共享的像素数据进行深度复制，从而确保QImage 是唯一一个使用当前返回值的函数。

另请参阅 scanLine()、sizeInBytes() 和constBits()。

const uchar *QImage::bits() const

这是一个重载函数。

请注意，QImage 使用隐式数据共享，但该函数不会对共享的像素数据进行深度复制，因为返回的数据是常量。

qsizetype QImage::bytesPerLine() const

返回每个图像扫描线的字节数。

如果height() 非零，则等同于sizeInBytes() /height()。

另请参见 scanLine()。

qint64 QImage::cacheKey() const

返回一个数字，用于标识此QImage 对象的内容。不同的QImage 对象只有在引用相同的内容时才能具有相同的密钥。

更改图像时，键值会发生变化。

QRgb QImage::color(int i) const

返回颜色表中位于索引i 处的颜色。第一种颜色位于索引 0。

图像颜色表中的颜色指定为 ARGB 四元组 (QRgb)。使用qAlpha()、qRed()、qGreen() 和qBlue() 函数获取颜色值成分。

另请参见 setColor()、pixelIndex() 和Pixel Manipulation 。

int QImage::colorCount() const

返回图像颜色表的大小。

请注意，对于 32-bpp 图像，colorCount() 返回 0，因为这些图像不使用颜色表，而是将像素值编码为 ARGB 四元组。

另请参阅 setColorCount() 和Image Information 。

QColorSpace QImage::colorSpace() const

如果定义了色彩空间，则返回图像的色彩空间。

另请参见 setColorSpace()。

QList<QRgb> QImage::colorTable() const

返回图像颜色表中包含的颜色列表，如果图像没有颜色表，则返回空列表

另请参阅 setColorTable()、colorCount() 和color()。

[since 6.4] QImage QImage::colorTransformed(const QColorTransform &transform) const &

返回使用transform 对图像中所有像素进行颜色转换后的图像颜色。

此函数在 Qt 6.4 中引入。

另请参阅 applyColorTransform()。

[since 6.8] QImage QImage::colorTransformed(const QColorTransform &transform, QImage::Format toFormat, Qt::ImageConversionFlags flags = Qt::AutoColor) const &

使用transform 对图像中的所有像素进行图像颜色转换，返回格式为toFormat 的图像。

指定的图像转换flags 控制在格式转换过程中如何处理图像数据。

此函数在 Qt 6.8 中引入。

另请参阅 applyColorTransform() 。

[since 6.4] QImage QImage::colorTransformed(const QColorTransform &transform) &&

这是一个重载函数。

返回使用transform 对图像中所有像素进行变换后的图像颜色。

此函数在 Qt 6.4 中引入。

另请参阅 applyColorTransform()。

[since 6.8] QImage QImage::colorTransformed(const QColorTransform &transform, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor) &&

这是一个重载函数。

返回使用transform 对图像中所有像素进行变换后的图像颜色。

此函数在 Qt 6.8 中引入。

另请参阅 applyColorTransform()。

const uchar *QImage::constBits() const

返回指向第一个像素数据的指针。

请注意，QImage 使用隐式数据共享，但该函数不会执行共享像素数据的深度复制，因为返回的数据是常量。

另请参阅 bits() 和constScanLine()。

const uchar *QImage::constScanLine(int i) const

返回索引为i 的扫描线上像素数据的指针。第一个扫描线位于索引 0 处。

扫描线数据最小为 32 位对齐。对于 64 位格式，它遵循 64 位整数的本地对齐方式（大多数平台为 64 位，但在 i386 平台上明显为 32 位）。

请注意，QImage 使用隐式数据共享，但该函数不会执行共享像素数据的深度复制，因为返回的数据是常量。

另请参见 scanLine() 和constBits()。

void QImage::convertTo(QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor)

将图像就地转换为给定的format ，必要时进行分离。

指定的图像转换flags 控制转换过程中图像数据的处理方式。

另请参阅 convertedTo()。

void QImage::convertToColorSpace(const QColorSpace &colorSpace)

将图像转换为colorSpace 。

如果图像没有有效的色彩空间，该方法不会执行任何操作。

另请参阅 convertedToColorSpace() 和setColorSpace()。

[since 6.8] void QImage::convertToColorSpace(const QColorSpace &colorSpace, QImage::Format format, Qt::ImageConversionFlags flags = Qt::AutoColor)

将图像转换为colorSpace 和format 。

如果图像没有有效的色彩空间，该方法不会执行任何操作，如果色彩空间与格式不兼容，该方法也不会执行任何操作。

指定的图像转换flags 可控制在格式转换过程中如何处理图像数据。

此函数在 Qt 6.8 中引入。

另请参阅 convertedToColorSpace() 和setColorSpace()。

QImage QImage::convertToFormat(QImage::Format format, const QList<QRgb> &colorTable, Qt::ImageConversionFlags flags = Qt::AutoColor) const

这是一个重载函数。

使用指定的colorTable ，返回转换为给定format 的图像副本。

从 RGB 格式转换为索引格式是一项缓慢的操作，将使用直接的最近色方法，不进行抖动。

QImage QImage::convertedToColorSpace(const QColorSpace &colorSpace) const

返回转换为colorSpace 的图像。

如果图像没有有效的色彩空间，则返回空QImage 。

另请参阅 convertToColorSpace() 和colorTransformed()。

QImage QImage::copy(const QRect &rectangle = QRect()) const

将图像的一个子区域作为新图像返回。

返回的图像是从该图像中的位置（rectangle.x()，rectangle.y()）复制的，其大小始终为给定的rectangle 。

对于 32 位 RGB 图像，这表示黑色；对于 32 位 ARGB 图像，这表示透明黑色；对于 8 位图像，这表示颜色表中索引为 0 的颜色，可以是任何颜色；对于 1 位图像，这表示Qt::color0 。

如果给定的rectangle 是空矩形，则会复制整个图像。

另请参阅 QImage() 。

QImage QImage::copy(int x, int y, int width, int height) const

这是一个重载函数。

返回的图像将从该图像中的 (x,y) 位置复制，并始终具有给定的width 和height 。在超出该图像的区域，像素将被设置为 0。

QImage QImage::createAlphaMask(Qt::ImageConversionFlags flags = Qt::AutoColor) const

从图像中的 alpha 缓冲区生成并返回 1-bpp 遮罩。如果图像格式为QImage::Format_RGB32 ，则返回空图像。

flags 参数是Qt::ImageConversionFlags 的比特-OR，用于控制转换过程。如果标记为 0，则会设置所有默认选项。

返回的图像具有小端位顺序（即图像格式为QImage::Format_MonoLSB ），您可以使用convertToFormat() 函数将其转换为大端位顺序（QImage::Format_Mono ）。

另请参阅 createHeuristicMask() 和Image Transformations 。

QImage QImage::createHeuristicMask(bool clipTight = true) const

为图像创建并返回一个 1-bpp 的启发式遮罩。

该函数的工作原理是从其中一个角选择一种颜色，然后从所有边缘开始去除该颜色的像素。四个角会投票决定屏蔽掉哪种颜色。如果是平局（这通常意味着此函数不适用于图像），则结果是任意的。

返回的图像具有小端位顺序（即图像格式为QImage::Format_MonoLSB ），您可以使用convertToFormat() 函数将其转换为大端位顺序 (QImage::Format_Mono)。

如果clipTight 为 true（默认值），遮罩的大小刚好可以覆盖像素；否则，遮罩会大于数据像素。

请注意，该函数不考虑 alpha 缓冲区。

另请参阅 createAlphaMask() 和Image Transformations 。

QImage QImage::createMaskFromColor(QRgb color, Qt::MaskMode mode = Qt::MaskInColor) const

根据给定的color 值为此图像创建并返回遮罩。如果mode 是 MaskInColor（默认值），则与color 匹配的所有像素都将成为遮罩中的不透明像素。如果mode 为 MaskOutColor，则与给定颜色匹配的所有像素都将是透明的。

另请参见 createAlphaMask() 和createHeuristicMask()。

int QImage::depth() const

返回图像的深度。

图像深度是指用于存储单个像素的比特数，也称为每像素比特数（bpp）。

支持的深度有 1、8、16、24、32 和 64。

另请参阅 bitPlaneCount(),convertToFormat(),Image Formats, 和Image Information 。

[since 6.2] QSizeF QImage::deviceIndependentSize() const

以独立于设备的像素为单位返回图像大小。

在计算用户界面尺寸时使用图像尺寸时应使用此值。

返回值等同于图像。size() / 图像。devicePixelRatio() 。

此函数在 Qt 6.2 中引入。

qreal QImage::devicePixelRatio() const

返回图像的设备像素比。这是设备像素与设备独立像素之间的比率。

QSize layoutSize = image.size() / image.devicePixelRatio()

默认值为 1.0。

另请参阅 setDevicePixelRatio() 和QImageReader 。

int QImage::dotsPerMeterX() const

返回一个物理量表中水平方向可容纳的像素数。该数字与dotsPerMeterY() 一起定义了图像的预期比例和纵横比。

另请参阅 setDotsPerMeterX() 和Image Information 。

int QImage::dotsPerMeterY() const

返回垂直方向上适合一个物理量表的像素数。该数字与dotsPerMeterX() 一起定义了图像的预期比例和纵横比。

另请参阅 setDotsPerMeterY() 和Image Information 。

void QImage::fill(uint pixelValue)

用给定的pixelValue 填充整个图像。

如果图像的深度为 1，则只使用最低位。如果您说 fill(0)、fill(2) 等，图像将被填充为 0。如果输入 fill(1)、fill(3) 等命令，图像将被填充为 1。如果深度为 8，则使用最低的 8 位；如果深度为 16，则使用最低的 16 位。

如果图像深度大于 32 位，则结果未定义。

另请参阅 depth() 和Image Transformations 。

void QImage::fill(Qt::GlobalColor color)

这是一个重载函数。

使用给定的color 填充图像，该颜色被描述为标准的全局颜色。

void QImage::fill(const QColor &color)

这是一个重载函数。

使用给定的color 填充整个图像。

如果图像的深度为 1，则在color 等于Qt::color1 的情况下填充 1；否则填充 0。

如果图像的深度为 8，则将用颜色表中与color 对应的索引填充图像（如果存在）；否则将填充 0。

QImage::Format QImage::format() const

返回图像的格式。

另请参见 Image Formats 。

[static, since 6.2] QImage QImage::fromData(QByteArrayView data, const char *format = nullptr)

从给定的QByteArrayView data 构建图像。加载器会尝试使用指定的format 读取图像。如果未指定format （默认值），加载程序会探测数据头以猜测文件格式。

如果指定了format ，它必须是QImageReader::supportedImageFormats() 返回的值之一。

如果加载图片失败，返回的图片将是空图片。

此函数在 Qt 6.2 中引入。

另请参阅 load(),save() 和Reading and Writing Image Files 。

[static] QImage QImage::fromData(const QByteArray &data, const char *format = nullptr)

这是一个重载函数。

从给定的QByteArray data 构建一个QImage 。

[static] QImage QImage::fromData(const uchar *data, int size, const char *format = nullptr)

这是一个重载函数。

从给定二进制data 的第一个size 字节构造一个QImage 。

[static, since 6.0] QImage QImage::fromHBITMAP(HBITMAP hbitmap)

返回等同于给定hbitmap 的QImage 。

HBITMAP 不存储有关 alpha 通道的信息。

在标准情况下，alpha 通道会被忽略，并创建一个完全不透明的图像（通常格式为QImage::Format_RGB32 ）。

不过也有使用 alpha 通道的情况，例如应用程序图标或系统盘图标。在这种情况下，应在返回的图像上调用reinterpretAsFormat(QImage::Format_ARGB32) ，以确保格式正确。

此函数在 Qt 6.0 中引入。

另请参阅 toHBITMAP() 和reinterpretAsFormat()。

[static, since 6.0] QImage QImage::fromHICON(HICON icon)

返回与给定icon 等价的QImage 。

此函数在 Qt 6.0 中引入。

另请参阅 toHICON()。

bool QImage::hasAlphaChannel() const

如果图像格式尊重 alpha 通道，则返回true ，否则返回false 。

另请参见 Image Information 。

int QImage::height() const

返回图像的高度。

另请参见 Image Information 。

void QImage::invertPixels(QImage::InvertMode mode = InvertRgb)

反转图像中的所有像素值。

只有当图像深度为 32 时，给定的反转mode 才有意义。默认的mode 是InvertRgb ，阿尔法通道保持不变。如果mode 是InvertRgba ，alpha 位也会被反转。

反转 8 位图像意味着用颜色索引 255 减i 的像素替换所有使用颜色索引i的像素。请注意，颜色表不会改变。

如果图像有预乘法 alpha 通道，则首先将图像转换为待反转的非预乘法图像格式，然后再转换回来。

另请参阅 Image Transformations 。

bool QImage::isGrayscale() const

对于 32 位图像，该函数等同于allGray()。

对于彩色索引图像，如果 color(i) 是QRgb(i, i, i)，则此函数返回true ，否则返回false 。

另请参见 allGray() 和Image Formats 。

bool QImage::isNull() const

如果是空图像，则返回true ，否则返回false 。

空图像的所有参数设置为零，没有分配数据。

bool QImage::load(const QString &fileName, const char *format = nullptr)

以给定的fileName 从文件中加载图像。如果图片加载成功，则返回true ；否则图片无效，并返回false 。

加载器会尝试使用指定的format （如 PNG 或 JPG）读取图片。如果未指定format （默认情况），则会根据文件后缀和文件头自动检测。详情请参阅QImageReader::setAutoDetectImageFormat() 。

文件名既可以指磁盘上的实际文件，也可以指应用程序的嵌入式资源。有关如何在应用程序的可执行文件中嵌入图像和其他资源文件的详细信息，请参阅资源系统概述。

另请参阅 Reading and Writing Image Files 。

bool QImage::load(QIODevice *device, const char *format)

这是一个重载函数。

该函数从给定的device 中读取QImage 。例如，它可用于将图像直接加载到QByteArray 中。

[since 6.2] bool QImage::loadFromData(QByteArrayView data, const char *format = nullptr)

从给定的QByteArrayView data 中加载图像。如果图片加载成功，则返回true ；否则图片无效，并返回false 。

加载器会尝试使用指定的format （如 PNG 或 JPG）读取图片。如果未指定format （默认情况），加载器会探测文件头以猜测文件格式。

此功能在 Qt 6.2 中引入。

另请参阅 Reading and Writing Image Files 。

bool QImage::loadFromData(const QByteArray &data, const char *format = nullptr)

这是一个重载函数。

从给定的QByteArray data 中加载图像。

bool QImage::loadFromData(const uchar *data, int len, const char *format = nullptr)

这是一个重载函数。

从给定二进制data 的前len 字节加载图像。

[since 6.0] void QImage::mirror(bool horizontal = false, bool vertical = true)

图像在水平和/或垂直方向的镜像，取决于horizontal 和vertical 设置为 true 或 false。

此函数在 Qt 6.0 中引入。

另请参阅 mirrored() 和Image Transformations 。

QPoint QImage::offset() const

返回图像相对于其他图像定位时的偏移像素数。

另请参阅 setOffset() 和Image Information 。

QRgb QImage::pixel(const QPoint &position) const

返回给定position 处像素的颜色。

如果position 无效，则结果未定义。

另请参阅 setPixel(),valid(),constBits(),constScanLine() 和Pixel Manipulation 。

QRgb QImage::pixel(int x, int y) const

这是一个重载函数。

返回坐标 (x,y) 处像素的颜色。

QColor QImage::pixelColor(const QPoint &position) const

以QColor 的形式返回给定position 处像素的颜色。

如果position 无效，则返回无效的QColor 。

另请参阅 setPixelColor(),setPixel(),valid(),constBits(),constScanLine() 和Pixel Manipulation 。

QColor QImage::pixelColor(int x, int y) const

这是一个重载函数。

以QColor 的形式返回坐标 (x,y) 处像素的颜色。

[noexcept] QPixelFormat QImage::pixelFormat() const

将QImage::Format 返回为QPixelFormat

int QImage::pixelIndex(const QPoint &position) const

返回给定position 处的像素索引。

如果position 无效，或者图像不是调色板图像（depth() > 8），则结果未定义。

另请参阅 valid()、depth() 和Pixel Manipulation 。

int QImage::pixelIndex(int x, int y) const

这是一个重载函数。

返回 (x,y) 处的像素索引。

QRect QImage::rect() const

返回图像的包围矩形（0, 0,width(),height() ）。

另请参见 Image Information 。

bool QImage::reinterpretAsFormat(QImage::Format format)

在不更改数据的情况下，将图像格式更改为format 。仅适用于相同深度的格式。

如果成功，则返回true 。

如果已知数据仅为不透明格式，该函数可用于将带有阿尔法通道的图像更改为相应的不透明格式，或在用新数据覆盖给定图像缓冲区之前更改其格式。

另请参阅 hasAlphaChannel() 和convertToFormat()。

[since 6.0] void QImage::rgbSwap()

交换所有像素的红色和蓝色分量值，有效地将 RGB 图像转换为 BGR 图像。

此函数在 Qt 6.0 中引入。

另请参阅 rgbSwapped() 和Image Transformations 。

bool QImage::save(const QString &fileName, const char *format = nullptr, int quality = -1) const

使用给定的图像文件format 和quality 因子，将图像保存到给定fileName 的文件中。如果format 是nullptr ，QImage 将尝试通过查看fileName 的后缀来猜测格式。

quality 因子的范围必须在 0 到 100 或 -1 之间。指定 0 可以获得小的压缩文件，指定 100 可以获得大的未压缩文件，指定-1（默认值）可以使用默认设置。

如果图像保存成功，则返回true ；否则返回false 。

另请参阅 Reading and Writing Image Files 。

bool QImage::save(QIODevice *device, const char *format = nullptr, int quality = -1) const

这是一个重载函数。

该函数将QImage 写入给定的device 。

例如，它可用于将图像直接保存到QByteArray 中：

QImage image;
QByteArray ba;
QBuffer buffer(&ba);
buffer.open(QIODevice::WriteOnly);
image.save(&buffer, "PNG"); // writes image into ba in PNG format

QImage QImage::scaled(const QSize &size, Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation) const

根据给定的aspectRatioMode 和transformMode ，返回按给定的size 定义的矩形缩放的图像副本。

• 如果aspectRatioMode 是Qt::IgnoreAspectRatio ，则图像将缩放到size 。
• 如果aspectRatioMode 是Qt::KeepAspectRatio ，则图像将缩放到size 内尽可能大的矩形内，并保持长宽比。
• 如果aspectRatioMode 是Qt::KeepAspectRatioByExpanding ，则图像将缩放到size 外尽可能小的矩形区域，并保持长宽比。

如果给定的size 为空，此函数将返回空图像。

另请参阅 isNull() 和Image Transformations 。

QImage QImage::scaled(int width, int height, Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation) const

这是一个重载函数。

根据给定的width 和height 以及给定的aspectRatioMode 和transformMode ，返回缩放为矩形的图像副本。

如果width 或height 为零或负数，此函数将返回空图像。

QImage QImage::scaledToHeight(int height, Qt::TransformationMode mode = Qt::FastTransformation) const

返回图像的缩放副本。返回的图像将使用指定的变换mode 缩放到给定的height 。

该函数会自动计算图像的宽度，以保持图像的比例。

如果给定的height 为 0 或负值，则返回空图像。

另请参见 Image Transformations 。

QImage QImage::scaledToWidth(int width, Qt::TransformationMode mode = Qt::FastTransformation) const

返回图像的缩放副本。返回的图像将使用指定的变换mode 缩放到给定的width 。

该函数会自动计算图像的高度，以保持图像的宽高比。

如果给定的width 为 0 或负值，则返回空图像。

另请参阅 Image Transformations 。

uchar *QImage::scanLine(int i)

返回索引为i 的扫描线上像素数据的指针。第一个扫描线位于索引 0 处。

扫描线数据最小为 32 位对齐。对于 64 位格式，它遵循 64 位整数的本地对齐方式（大多数平台为 64 位，但在 i386 平台上明显为 32 位）。

例如，删除图像中每个像素的绿色分量：

for (int y = 0; y < image.height(); ++y) {
    QRgb *line = reinterpret_cast<QRgb*>(image.scanLine(y));
    for (int x = 0; x < image.width(); ++x) {
        QRgb &rgb = line[x];
        rgb = qRgba(qRed(rgb), qGreen(0), qBlue(rgb), qAlpha(rgb));
    }
}

另请参阅 bytesPerLine()、bits()、Pixel Manipulation 和constScanLine()。

const uchar *QImage::scanLine(int i) const

这是一个重载函数。

void QImage::setAlphaChannel(const QImage &alphaChannel)

将此图像的 alpha 通道设置为给定的alphaChannel 。

如果alphaChannel 是 8 位 alpha 图像，则直接使用 alpha 值。否则，alphaChannel 将转换为 8 位灰度，并使用像素值的强度。

如果图像已经有一个 alpha 通道，现有的 alpha 通道将与新的 alpha 通道相乘。如果图像没有 alpha 通道，则会转换为有 alpha 通道的格式。

该操作类似于使用QPainter::CompositionMode_DestinationIn 在该图像上绘制alphaChannel 作为 alpha 图像。

另请参阅 hasAlphaChannel(),Image Transformations, 和Image Formats 。

void QImage::setColor(int index, QRgb colorValue)

将颜色表中给定index 处的颜色设置为给定的colorValue 。颜色值是 ARGB 四元组。

如果index 超出了颜色表的当前大小，则使用setColorCount() 扩展。

另请参见 color()、colorCount()、setColorTable() 和Pixel Manipulation 。

void QImage::setColorCount(int colorCount)

调整颜色表的大小，使其包含colorCount 条目。

如果颜色表被扩展，所有额外的颜色都将设置为透明色（即qRgba(0,0,0,0,0)）。

使用图像时，颜色表必须足够大，以包含图像中所有像素/索引值的条目，否则结果将是未定义的。

另请参见 colorCount()、colorTable()、setColor() 和Image Transformations 。

void QImage::setColorSpace(const QColorSpace &colorSpace)

将图像色彩空间设置为colorSpace ，而不对图像数据进行任何转换。

另请参阅 colorSpace().

void QImage::setColorTable(const QList<QRgb> &colors)

将用于将颜色索引转换为QRgb 值的颜色表设置为指定的colors 。

使用图像时，颜色表必须足够大，以包含图像中所有像素/索引值的条目，否则结果将是未定义的。

另请参阅 colorTable(),setColor() 和Image Transformations 。

void QImage::setDevicePixelRatio(qreal scaleFactor)

设置图像的设备像素比。这是图像像素与独立于设备的像素之间的比率。

scaleFactor 的默认值是 1.0。将其设置为其他值会有两种效果：

在图像上打开的 QPainters 将被缩放。例如，如果在比例为 2.0 的 200x200 图像上绘画，则有效（与设备无关）绘画边界为 100x100。

Qt 中根据图像大小计算布局几何图形的代码路径将考虑该比例：QSize layoutSize = image.size() / image.devicePixelRatio() 这样做的净效果是，图像显示为高 DPI 图像，而不是大图像（请参阅Drawing High Resolution Versions of Pixmaps and Images ）。

另请参阅 devicePixelRatio() 和deviceIndependentSize()。

void QImage::setDotsPerMeterX(int x)

在x 中设置一个物理量表中水平方向可容纳的像素数。

该数字与dotsPerMeterY() 一起定义了图像的预期比例和纵横比，并决定了QPainter 在图像上绘制图形的比例。当图像在其他绘画设备上呈现时，它不会改变图像的比例或宽高比。

另请参阅 dotsPerMeterX() 和Image Information 。

void QImage::setDotsPerMeterY(int y)

在y 中设置垂直方向上可容纳的像素数。

该数字与dotsPerMeterX() 一起定义了图像的预期比例和纵横比，并决定了QPainter 在图像上绘制图形的比例。当图像在其他绘画设备上呈现时，它不会改变图像的比例或宽高比。

另请参阅 dotsPerMeterY() 和Image Information 。

void QImage::setOffset(const QPoint &offset)

设置图像相对于其他图像定位时的偏移像素数，即offset 。

另请参阅 offset() 和Image Information 。

void QImage::setPixel(const QPoint &position, uint index_or_rgb)

将给定position 的像素索引或颜色设置为index_or_rgb 。

如果图像格式是单色或调色板，给定的index_or_rgb 值必须是图像颜色表中的索引，否则参数必须是QRgb 值。

如果position 不是图像中的有效坐标对，或者在单色和调色板图像中index_or_rgb >=colorCount() ，结果将是未定义的。

另请参阅 pixel() 和Pixel Manipulation 。

void QImage::setPixel(int x, int y, uint index_or_rgb)

这是一个重载函数。

将 (x,y) 处的像素索引或颜色设置为index_or_rgb 。

void QImage::setPixelColor(const QPoint &position, const QColor &color)

将给定的position 处的颜色设置为color 。

如果position 不是图像中的有效坐标对，或者图像格式是单色或调色板格式，结果将是未定义的。

另请参阅 pixelColor(),pixel(),bits(),scanLine() 和Pixel Manipulation 。

void QImage::setPixelColor(int x, int y, const QColor &color)

这是一个重载函数。

将 (x,y) 处的像素颜色设置为color 。

void QImage::setText(const QString &key, const QString &text)

将图像文本设置为给定的text ，并与给定的key 关联。

如果只想存储单个文本块（如 "评论 "或描述），则可以传递一个空键，或使用 "描述 "这样的通用键。

调用save() 或QImageWriter::write() 时，图像文本将嵌入图像数据中。

并非所有图像格式都支持嵌入文本。您可以使用QImageWriter::supportsOption() 查找特定图像或格式是否支持嵌入文本。我们举例说明：

    QImageWriterwriter; writer.setFormat("png");if(writer.supportsOption(QImageIOHandler::Description))        qDebug() << "Png supports embedded text";

您可以使用QImageWriter::supportedImageFormats() 查找您可以使用的图像格式。

另请参阅 text() 和textKeys()。

QSize QImage::size() const

返回图像的大小，即width() 和height()。

另请参阅 Image Information 和deviceIndependentSize()。

qsizetype QImage::sizeInBytes() const

以字节为单位返回图像数据大小。

另请参阅 bytesPerLine(),bits() 和Image Information 。

[noexcept] void QImage::swap(QImage &other)

将此图像与other 互换。该操作速度非常快，从未出现过故障。

QString QImage::text(const QString &key = QString()) const

返回与给定key 相关联的图像文本。如果指定的key 是空字符串，则返回整个图像文本，每个键-文本对以换行分隔。

另请参阅 setText() 和textKeys()。

QStringList QImage::textKeys() const

返回此图像的文本键。

您可以将这些键与text() 一起使用，列出某个键的图像文本。

另请参阅 text()。

CGImageRef QImage::toCGImage() const

创建与此QImage 等价的CGImage ，并返回CGImageRef 句柄。

返回的 CGImageRef 参与QImage 的隐式共享，并持有对QImage 数据的引用。CGImage 是不可变的，永远不会脱离QImage 。向QImage 写入时会像往常一样脱离。

该函数速度很快，不会复制或转换图像数据。

支持以下图像格式，并将映射到相应的本地图像类型：

不支持其他格式；在这种情况下，此函数将返回空 CGImageRef。该函数的用户可以先将QImage 转换为支持的格式，例如Format_ARGB32_Premultiplied 。

CGImageRef 的色彩空间设置为 sRGB 色彩空间。

[since 6.0] HBITMAP QImage::toHBITMAP() const

创建与HBITMAP 等价的QImage 。

返回HBITMAP 句柄。

调用者有责任在使用后释放HBITMAP 数据。

要与标准 GDI 调用（如BitBlt() ）一起使用，图像格式应为QImage::Format_RGB32 。

将生成的 HBITMAP 用于AlphaBlend() GDI 函数时，图像格式应为QImage::Format_ARGB32_Premultiplied （使用convertToFormat() ）。

将生成的 HBITMAP 用作应用程序图标或系统托盘图标时，图像格式应为QImage::Format_ARGB32 。

该功能在 Qt 6.0 中引入。

另请参阅 fromHBITMAP() 和convertToFormat()。

[since 6.0] HICON QImage::toHICON(const QImage &mask = {}) const

创建与QPixmap 对应的HICON ，并应用mask 的掩码。

如果mask 不是空值，则需要是QImage::Format_Mono 格式。返回HICON 句柄。

调用者有责任在使用后释放HICON 数据。

此函数在 Qt 6.0 中引入。

另请参阅 fromHICON() 。

[static noexcept] QImage::Format QImage::toImageFormat(QPixelFormat format)

将format 转换为QImage::Format

[static noexcept] QPixelFormat QImage::toPixelFormat(QImage::Format format)

将format 转换为QPixelFormat

QImage QImage::transformed(const QTransform &matrix, Qt::TransformationMode mode = Qt::FastTransformation) const

返回使用给定变换matrix 和变换mode 变换后的图像副本。

返回的图像通常与原始图像的{图像格式}{格式}相同。但是，复杂变换可能会导致图像中并非所有像素都被原始图像的变换像素覆盖。在这种情况下，这些背景像素将被分配一个透明色值，而转换后的图像将被赋予一个带有 alpha 通道的格式，即使原始图像并不带 alpha 通道。

转换后的matrix 会进行内部调整，以补偿不必要的平移；也就是说，生成的图像是包含原始图像所有转换点的最小图像。使用trueMatrix() 函数可获取用于变换图像的实际矩阵。

与其他重载不同，该函数可用于对图像进行透视变换。

另请参阅 trueMatrix() 和Image Transformations 。

[static] QTransform QImage::trueMatrix(const QTransform &matrix, int width, int height)

用给定的width 、height 和matrix 返回用于变换图像的实际矩阵。

使用transformed() 函数变换图像时，变换矩阵会进行内部调整，以补偿不必要的平移，即transformed() 返回包含原始图像所有变换点的最小图像。此函数返回修改后的矩阵，它能将原始图像中的点正确映射到新图像中。

与其他重载不同，此函数创建的变换矩阵可用于对图像进行透视变换。

另请参阅 transformed() 和Image Transformations 。

bool QImage::valid(const QPoint &pos) const

如果pos 是图像中的有效坐标对，则返回true ；否则返回false 。

另请参阅 rect() 和QRect::contains()。

bool QImage::valid(int x, int y) const

这是一个重载函数。

如果QPoint(x,y) 是图像中的有效坐标对，则返回true ；否则返回false 。

int QImage::width() const

返回图像的宽度。

另请参见 Image Information 。

QVariant QImage::operator QVariant() const

以QVariant 的形式返回图像。

bool QImage::operator!=(const QImage &image) const

如果此图像和给定的image 内容不同，则返回true ；否则返回false 。

比较过程可能会比较慢，除非有一些明显的不同，例如宽度不同，在这种情况下函数会很快返回。

另请参见 operator=()。

[noexcept] QImage &QImage::operator=(QImage &&other)

Move-assignsother 到此QImage 实例。

QImage &QImage::operator=(const QImage &image)

将给定image 的浅层副本分配给此图像，并返回此图像的引用。

有关浅层副本的更多信息，请参阅隐式数据共享文档。

另请参阅 copy() 和QImage()。

bool QImage::operator==(const QImage &image) const

如果该图片与给定的image 内容相同，则返回true ；否则返回false 。

比较过程可能会比较慢，除非有一些明显的差异（如大小或格式不同），在这种情况下，函数会快速返回。

另请参阅 operator=()。