QImage Class

成员函数文档

[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() 对其进行充分扩展。

与接受非 const 数据缓冲区的类似 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 指定每行的字节数（步长）。

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

如果format 采用索引颜色格式，则图像颜色表初始为空，必须在使用图像之前通过setColorCount() 或setColorTable() 对其进行充分扩展。

与接受非const数据缓冲区的类似 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 指定每行的字节数（步长）。

在 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 使用了隐式数据共享，但该函数不会对共享的像素数据进行深度复制，因为返回的数据是 const 类型。

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 使用了隐式数据共享，但本函数不会对共享的像素数据进行深度复制，因为返回的数据是 const 类型。

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

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

返回指向索引为i 的扫描行中像素数据的指针。第一条扫描行的索引为0。

扫描行数据至少按 32 位对齐。对于 64 位格式，它遵循 64 位整数的本地对齐方式（在大多数平台上为 64 位，但在 i386 平台上为 32 位）。

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

另请参阅 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()。

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

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

另请参阅 convertTo() 和Image Formats 。

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

返回一张已转换为指定format 格式的图像副本，转换时使用指定的colorTable 。

从RGB格式转换为索引格式是一项耗时的操作，将采用简单的最近色法，不进行抖动处理。

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

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

这些函数在 Qt 6.0 中引入。

另请参见 convertTo() 和Image Formats 。

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

返回转换为colorSpace 的图像。

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

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

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

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

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

这些函数在 Qt 6.8 中引入。

另请参阅 colorTransformed()。

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

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

返回的图像从本图像的坐标 (rectangle.x(),rectangle.y()) 处复制而来，其尺寸始终与给定的rectangle 一致。

在该图像以外的区域，像素将被设置为 0。对于 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

根据该图像的阿尔法缓冲区构建并返回一个 1-bpp 掩码。如果图像格式为QImage::Format_RGB32 ，则返回一个空图像。

flags 参数是Qt::ImageConversionFlags 的按位或（bitwise-OR）组合，用于控制转换过程。若将flags参数设为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 为真（默认值），则蒙版的大小刚好足以覆盖像素；否则，蒙版会比数据像素大。

请注意，此函数会忽略 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

返回图像以设备无关像素为单位的尺寸。

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

该返回值等同于 image.size() / image.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。

[since 6.9] void QImage::flip(Qt::Orientations orient = Qt::Vertical)

根据orient 的设置，沿水平和/或垂直方向翻转或镜像图像。

该函数在 Qt 6.9 中引入。

另请参阅 flipped(Qt::Orientations) 和Image Transformations 。

返回图像的翻转或镜像版本，具体是沿水平方向还是垂直方向进行镜像，取决于orient 。

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

这些函数是在 Qt 6.9 中引入的。

另请参阅 flip(Qt::Orientations) 和Image Transformations 。

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

如果图像的格式支持阿尔法通道，则返回true ；否则返回false 。

另请参阅 Image Information 。

int QImage::height() const

返回图像的高度。

另请参阅 Image Information 。

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

将图像中的所有像素值进行反转。

给定的反转参数mode 仅在图像深度为32时才有意义。默认的mode 为InvertRgb ，这会保持Alpha通道不变。如果mode 为InvertRgba ，则Alpha位也会被反转。

对 8 位图像进行反转，意味着将所有使用颜色索引i的像素替换为使用颜色索引 255 减去i 的像素。对于 1 位图像也是如此。请注意，颜色表不会发生改变。

如果图像具有预乘α通道，则会先将图像转换为非预乘图像格式进行反转，然后再次转换回来。

另请参阅 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, until 6.13] void QImage::mirror(bool horizontal = false, bool vertical = true)

该函数计划在 6.13 版本中被废弃。

请改用 flip(Qt::Orientations)。

根据horizontal 和vertical 的设置为 true 还是 false，将沿水平和/或垂直方向对图像进行镜像翻转。

该函数在 Qt 6.0 中引入。

另请参阅 mirrored() 和Image Transformations 。

该函数计划在 6.13 版本中被废弃。

请改用 flipped(Qt::Orientations)。

返回图像的镜像，具体是水平方向还是垂直方向的镜像，取决于 `horizontal ` 和 `vertical ` 是否设置为 true 或 false。

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

另请参阅 mirror() 和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

返回位于给定坐标position 处的像素颜色，格式为QColor 。

如果坐标position 无效，则返回一个无效的QColor 。

另请参阅 setPixelColor()、setPixel()、valid()、constBits()、constScanLine() 以及Pixel Manipulation 。

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

返回坐标为 (x,y) 的像素颜色，类型为QColor 。

[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 。

若已知数据仅为不透明数据，则可使用此函数将带有Alpha通道的图像转换为对应的不透明格式；或者在用新数据覆盖给定图像缓冲区之前，先更改其格式。

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

[since 6.0] void QImage::rgbSwap()

将所有像素的红色和蓝色分量值互换，从而将 RGB 图像转换为 BGR 图像。

该函数自 Qt 6.0 起引入。

另请参阅 rgbSwapped() 和Image Transformations 。

返回一个QImage 数组，其中所有像素的红色和蓝色分量的值已被互换，从而将RGB图像转换为BGR图像。

原始的 `QImage ` 对象不会被修改。

另请参阅 rgbSwap() 和Image Transformations 。

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

将图像保存到指定fileName 的文件中，使用给定的图像文件format 和quality 因子。如果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

返回一张图像的副本，该副本已根据给定的size ，并参照给定的aspectRatioMode 和transformMode ，缩放为矩形。

• 如果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 ` 作为透明图像覆盖在此图像之上。

另请参阅 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)）。

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

另请参阅 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 关联起来。

如果您只想存储一个文本块（即“注释”或仅为描述），可以传入一个空键，或者使用“Description”这样的通用键。

当您调用save()或QImageWriter::write()时，图像文本会被嵌入到图像数据中。

并非所有图像格式都支持嵌入文本。你可以通过调用QImageWriter::supportsOption()来判断特定图像或格式是否支持嵌入文本。以下是一个示例：

    QImageWriter writer;
    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

创建一个与QImage 等效的HBITMAP 对象。

返回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 通道的格式，即使原始图像本身没有该通道。

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 。

QImage::operator QVariant() const

将图像作为QVariant 返回。

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

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

该比较可能较慢，除非存在明显差异（例如宽度不同），在这种情况下该函数将快速返回结果。

另请参阅 operator=()。

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

将other 分配给此QImage 实例。

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

将给定image 的浅拷贝分配给此图像，并返回对此图像的引用。

有关浅拷贝的更多信息，请参阅《隐式数据共享》文档。

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

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

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

该比较可能比较耗时，除非存在明显差异（例如尺寸或格式不同），这种情况下函数将快速返回结果。

另请参阅 operator=()。