QImage类

成员函数文档

返回给定 format 的图像副本。

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

另请参阅：convertTo() 和 Image Formats。

返回给定 format 的图像副本。

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

此函数自 Qt 6.0 起被引入。

另请参阅：convertTo() 和 Image Formats。

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

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

另请参阅 mirror() 和 图像变换。

返回一个 QImage，其中所有像素的红色和蓝色分量的值已交换，实际上将 RGB 图像转换为 BGR 图像。

原始 QImage 不会被修改。

另请参阅 rgbSwap() 和 图像变换。

[noexcept] QImage::QImage()

构造一个空图像。

另请参阅 isNull()。

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

使用指定的 size 和 format 构造图像。

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

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

使用指定的 width、height 和 format 构造图像。

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

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

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

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

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

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

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

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

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

与接收非const数据缓冲区的相似QImage构造函数不同，这个版本永远不会修改缓冲区的内容。例如，调用QImage::bits()将返回图像的深拷贝，而不是传递给构造函数的缓冲区。这允许从原始数据创建QImage，同时避免原始数据被更改的可能性。

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

使用现有的内存缓冲区 data 创建具有给定 width、height 和 format 的图像。必须以像素为单位指定宽度和高度。bytesPerLine 指定了每行的字节数（行步长）。

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

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

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

使用现有的内存缓冲区 data 创建具有给定 width、height 和 format 的图像。必须以像素为单位指定宽度和高度。bytesPerLine 指定了每行的字节数（行步长）。

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

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

与接收非const数据缓冲区的相似QImage构造函数不同，这个版本永远不会修改缓冲区的内容。例如，调用QImage::bits()将返回图像的深拷贝，而不是传递给构造函数的缓冲区。这允许从原始数据创建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 QString &fileName, const char *format = nullptr)

构造一个图像，并尝试从指定的fileName文件中加载图像。

加载器尝试使用指定的format读取图像。如果format未指定（这是默认值），则会根据文件的扩展名和头信息进行自动检测。有关详细信息，请参阅{QImageReader::setAutoDetectImageFormat()}{QImageReader}。

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

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

另请参阅isNull() 和 读写图像文件。

QImage::QImage(const QImage &image)

构造给定的image的一个浅拷贝。

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

另请参阅copy()。

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

移动构造一个QImage实例，使其指向other所指向的同一对象。

[虚拟 noexcept] QImage::~QImage()

销毁图像并进行清理。

bool QImage::allGray() const

如果图像中所有颜色都是灰度色调（即它们的红色、绿色和蓝色分量相等），则返回true；否则为false。

请注意，此函数对没有颜色表的图像较慢。

另请参阅isGrayscale()。

void QImage::applyColorTransform(const QColorTransform &transform)

将颜色变换transform应用到图像中的所有像素上。

int QImage::bitPlaneCount() const

返回图像中的位平面数。

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

另请参阅depth()、format() 和 图像格式。

uchar *QImage::bits()

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

请注意，QImage使用了隐式数据共享。此函数执行共享像素数据的深拷贝，从而确保此QImage是该返回值的唯一使用者。

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

const uchar *QImage::bits() const

这是一个重载函数。

请注意，QImage使用<্implict data sharing（隐式数据共享），但此函数不会执行对共享像素数据的深度复制，因为返回的数据是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和像素操作。

int QImage::colorCount() const

返回图像颜色表的大小。

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

另请参阅setColorCount和图像信息。

QColorSpace QImage::colorSpace() const

如果已定义颜色空间，则返回图像的颜色空间。

另请参阅setColorSpace。

QList<QRgb> QImage::colorTable() const

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

另请参阅setColorTable，colorCount和color。

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

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

此函数是在 Qt 6.4 中引入的。

另请参阅applyColorTransform()。

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

这是一个重载函数。

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

此函数是在 Qt 6.4 中引入的。

另请参阅applyColorTransform()。

const uchar *QImage::constBits() const

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

请注意，QImage使用<্implict data sharing（隐式数据共享），但此函数不会执行对共享像素数据的深度复制，因为返回的数据是const。

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

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

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

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

请注意，QImage使用<্implict data sharing（隐式数据共享），但此函数不会执行对共享像素数据的深度复制，因为返回的数据是const。

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

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

就地将图像转换为给定的 格式，如有必要则分离。

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

另请参阅convertedTo()。

void QImage::convertToColorSpace(const QColorSpace &colorSpace)

将图像转换为 colorSpace。

如果图像没有有效的颜色空间，则方法不做任何操作。

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

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

这是一个重载函数。

返回图像的副本，并转换为给定的 格式，使用指定的 颜色表。

从 RGB 格式到索引格式的转换是一个缓慢的操作，并且将使用简单的最近颜色方法，不进行抖动。

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

返回转换为 颜色空间 的图像。

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

另请参阅convertToColorSpace()。

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

从本图像的alpha缓冲区中构建并返回一个1-bpp的蒙版。如果图像的格式是QImage::Format_RGB32，返回一个空图像。

flags参数是Qt::ImageConversionFlags的按位或组合，用于控制转换过程。传递0给标志设置所有默认选项。

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

另请参阅createHeuristicMask() 和图像转换。

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

为本图像创建并返回一个1-bpp的启发式蒙版。

该函数通过从一个角落中选择一种颜色，然后从所有边缘开始移除该颜色的像素来完成。四个角落对要屏蔽的颜色进行投票。如果有平局（这通常意味着该函数不适用于该图像），结果将是任意的。

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

如果clipTight为真（默认值），则蒙版的大小刚好足以覆盖像素；否则，蒙版将比数据像素大。

请注意，此函数不忽略alpha缓冲区。

另请参阅createAlphaMask() 和图像转换。

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

根据给定的color值创建并返回本图像的蒙版。如果mode是MaskInColor（默认值），则所有匹配的颜色像素在蒙版中将是不透明的。如果mode是MaskOutColor，则所有匹配的颜色像素在蒙版中将是不透明的。

另请参阅 createAlphaMask() 和 createHeuristicMask().

int QImage::depth() const

返回图像的深度。

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

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

另请参阅 bitPlaneCount()，convertToFormat()，图像格式 和 图像信息。

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

返回图像在设备独立像素中的大小。

在用户界面大小计算中使用图像大小时应使用此值。

返回值等价于 image.size() / image.devicePixelRatio()。

此函数在 Qt 6.2 中引入。

qreal QImage::devicePixelRatio() const

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

当根据图像大小计算布局几何时使用此函数：QSize 布局大小 = image.size() / image.devicePixelRatio()

默认值为 1.0。

另请参阅 setDevicePixelRatio() 和 QImageReader。

int QImage::dotsPerMeterX() const

返回水平方向上在物理米中可以容纳的像素数。与 dotsPerMeterY 一起，这个数字定义了图像的预期缩放和宽高比。

另请参阅 setDotsPerMeterX() 和 图像信息。

int QImage::dotsPerMeterY() const

返回垂直方向上在物理米中可以容纳的像素数。与 dotsPerMeterX 一起，这个数字定义了图像的预期缩放和宽高比。

另请参阅 setDotsPerMeterY() 和 图像信息。

void QImage::fill(uint pixelValue)

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

如果此图像的深度为 1，则仅使用最低位。如果您说填充(0)，填充(2) 等，则图像填充 0。如果你说填充(1)，填充(3) 等，则图像填充 1。如果深度为 8，则使用最低 8 位，如果深度为 16 则使用最低 16 位。

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

另请参阅 depth() 和 图像转换。

void QImage::fill(const QColor &color)

这是一个重载函数。

用给定颜色填充整个图像。

如果图像深度为1，则当颜色等于Qt::color1时，图像将与1填充；否则为0。

如果图像深度为8，则当颜色表中有对应颜色时，图像将被相应索引填充；否则为0。

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

这是一个重载函数。

使用标准全局颜色描述的给定颜色填充图像。

QImage::Format QImage::format() const

返回图像的格式。

参见图像格式。

[静态, 自6.2以来] QImage QImage::fromData(QByteArrayView data, const char *format = nullptr)

从给定的QByteArrayView 数据构建图像。加载器尝试使用指定的格式读取图像。如果没有指定格式（默认情况），加载器将探测数据以猜测文件格式。

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

如果图像加载失败，返回的图像将为空图像。

此函数在 Qt 6.2 中引入。

参见load()，save()和读取和写入图像文件。

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

这是一个重载函数。

从给定的二进制数据的前大小个字节构建QImage。

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

这是一个重载函数。

从给定的QByteArray 数据构建QImage。

[静态, 自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。

[静态，自6.0以来] QImage QImage::fromHICON(HICON icon)

返回一个与指定的 icon 等效的 QImage。

此函数自 Qt 6.0 起被引入。

另请参阅 toHICON()。

bool QImage::hasAlphaChannel() const

如果图像具有支持alpha通道的格式，则返回 true，否则返回 false。

另请参阅 图像信息。

int QImage::height() const

返回图像的高度。

另请参阅 图像信息。

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

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

所提供的反转 mode 只有在图像深度为32时才有意义。默认 mode 为 InvertRgb，此时alpha通道保持不变。如果 mode 是 InvertRgba，则alpha位也被反转。

反转8位图像意味着用颜色索引 255 - i 的像素替换颜色索引 的所有像素。对于1位图像也是如此。注意，颜色表不会被更改。

如果图像具有预乘的alpha通道，则首先将图像转换为未预乘的图像格式以进行反转，然后将其转换回来。

另请参阅 图像变换。

bool QImage::isGrayscale() const

对于32位图像，此函数与 allGray() 等效。

对于索引彩色图像，如果颜色表中的所有颜色(i)都是 QRgb(i, i, i)，则此函数返回 true，否则返回 false。

另请参阅 allGray() 和 图像格式。

bool QImage::isNull() const

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

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

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

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

加载器尝试使用指定的 format 读取图像，例如PNG或JPG。如果没有指定 format（这是默认值），则根据文件的扩展名和标题自动检测。有关详细信息，请参阅 QImageReader::setAutoDetectImageFormat。

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

另请参阅 读取和写入图像文件。

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

这是一个重载函数。

此函数从给定的 device 中读取一个 QImage。这可以用来直接将图像加载到 QByteArray 中。

[自6.2版本开始] bool QImage::loadFromData(QByteArrayView data, const char *format = nullptr)

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

加载器尝试使用指定的 format 读取图像，例如 PNG 或 JPG。如果未指定 format（默认行为），则加载器会检查文件头以猜测文件格式。

此函数在 Qt 6.2 中引入。

另请参阅 读取和写入图像文件。

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

这是一个重载函数。

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

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

这是一个重载函数。

从给定的 QByteArray data 加载图像。

[自6.0版本开始] void QImage::mirror(bool horizontal = false, bool vertical = true)

根据 horizontal 和 vertical 是否设置为 true 或 false，在水平和/或垂直方向上镜像图像。

此函数自 Qt 6.0 起被引入。

另请参阅 mirrored() 和 图像变换。

QPoint QImage::offset() const

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

另请参阅 setOffset() 和 图像信息。

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

返回给定 position 的像素颜色。

如果 position 不有效，结果未定义。

另请参阅 setPixel(), valid(), constBits(), constScanLine()，和 像素操作。

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()，以及 像素操作。

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

这是一个重载函数。

返回坐标(x，y)上的像素颜色，作为QColor。

[noexcept] QPixelFormat QImage::pixelFormat() const

返回图像格式作为QPixelFormat。

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

返回给定位置position的像素索引。

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

另请参阅 valid()，depth()，和 像素操作。

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

这是一个重载函数。

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

QRect QImage::rect() const

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

另请参阅 图像信息。

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

不更改数据，将图像格式更改为format。仅在具有相同深度的格式之间操作。

如果成功，则返回 true。

此函数可以用来将具有alpha通道的图像更改为相应的不透明格式，如果已知数据只包含不透明信息，或者更改一个给定图像缓冲区的格式，在用新数据覆盖之前。

另请参阅 hasAlphaChannel() 和 convertToFormat。

[since 6.0] void QImage::rgbSwap()

交换所有像素的红色和蓝色组件的值，实际上将RGB图像转换为BGR图像。

此函数自 Qt 6.0 起被引入。

另请参阅 rgbSwapped() 和 图像转换。

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

将图像保存到指定名称的文件中，使用指定的图像文件格式和质量因子。如果format为nullptr，则QImage会尝试通过查看fileName的扩展名来猜测格式。

质量因子必须在0到100或-1之间。指定0可以获得较小的压缩文件，指定100可以获得较大的未压缩文件，默认-1（系统默认设置）。

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

另请参阅 读取和写入图像文件。

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，则将图像缩放到一个尽可能大的矩形，但保留其宽高比。
• 如果aspectRatioMode为Qt::KeepAspectRatioByExpanding，则将图像缩放到一个尽可能小的矩形，外部小于size，但保留其宽高比。

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

另请参阅isNull()和图像变换。

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 QuincyImage::scaledToHeight(int height, Qt::TransformationMode mode = Qt::FastTransformation) const

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

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

如果给定的 高度 为 0 或负数，则返回一个空图像。

另请参阅 图像变换。

QImage QImage::scaledToWidth(int 宽度, Qt::TransformationMode 模式 = Qt::FastTransformation) const

返回图像的缩放副本。返回的图像使用指定的 模式 缩放至给定的 宽度。

这个函数会自动计算图像的高度以保持其纵横比。

如果给定的 宽度 为 0 或负数，则返回一个空图像。

另请参阅 图像变换。

uchar *QImage::scanLine(int 行号)

返回指向索引 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 行号) 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 索引, QRgb 颜色值)

将颜色表中的给定 索引 处的颜色设置为给定的 颜色值。颜色值是一个 ARGB 四元组。

如果 索引 超出当前颜色表的大小，它将使用 setColorCount() 扩展。

另请参阅 color、colorCount、setColorTable 和 Pixel Manipulation。

void QImage::setColorCount(int 颜色数)

调整颜色表的大小以包含 colorCount 个条目。

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

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

另请参阅 colorCount()，colorTable()，setColor()，以及 图像变换。

void QImage::setColorSpace(const QColorSpace &colorSpace)

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

另请参阅 colorSpace。

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

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

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

另请参阅 colorTable，setColor，以及 图像变换。

void QImage::setDevicePixelRatio(qreal scaleFactor)

设置图像的设备像素比。这是图像像素与设备无关像素之间的比率。

默认的 scaleFactor 为 1.0。将其实例设置为其他值有两个效果

打开图像的 QPainters 将进行缩放。例如，如果在一个 200x200 的图像上以 2.0 的比率进行绘画，则有效（设备无关）绘画范围将是 100x100。

基于图像大小计算布局几何形状的 Qt 代码路径将考虑比率：QSize 布局大小 = 图像.size() / 图像.devicePixelRatio。这将导致图像以高分辨率图像而不是大图像的形式显示（请参阅 绘制位图和高分辨率图像的高分辨率版本）。

另请参阅 devicePixelRatio() 和 deviceIndependentSize。

void QImage::setDotsPerMeterX(int x)

将水平放置一行像素占物理米的像素数设置为 x。

与 dotsPerMeterY 一起，此数字定义了图像的预定缩放和宽高比，并决定 QPainter 在图像上绘制图形的缩放。它不会改变图像在其他绘画设备上的缩放或宽高比。

另请参阅 dotsPerMeterX 和 图像信息。

void QImage::setDotsPerMeterY(int y)

将垂直放置一行像素占物理米的像素数设置为 y。

与dotsPerMeterX()一起，此数字定义了图像期望的缩放比和宽高比，并决定了QPainter在图像上绘制图形时的缩放比例。当图像在其他绘图设备上渲染时，它不会改变图像的缩放比或宽高比。

另请参阅dotsPerMeterY()和图像信息。

void QImage::setOffset(const QPoint &offset)

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

另请参阅offset()和图像信息。

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

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

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

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

另请参阅pixel()和像素操作。

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()和像素操作。

void QImage::setPixelColor(int x, int , 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是一个空字符串，则返回整个图像文本，其中每个关键-text对用换行符分隔。

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

[静态noexcept] QImage::Format QImage::toImageFormat(QPixelFormat format)

将format转换为QImage::Format

[静态noexcept] QPixelFormat QImage::toPixelFormat(QImage::Format format)

将format转换为QPixelFormat

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

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

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

该转换矩阵内部自动调整以补偿不希望的平移；即所生成的图像是最小的包含原始图像所有转换点的图像。使用trueMatrix()函数检索用于转换图像的实际矩阵。

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

另请参阅trueMatrix()和图像变换。

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

返回用于根据给定的宽度、高度和矩阵转换图像的实际矩阵。

当使用transformed()函数转换图像时，转换矩阵内部自动调整以补偿不希望的平移，即transformed()返回包含原始图像所有转换点的最小图像。此函数返回修改后的矩阵，它将正确地将原始图像中的点映射到新图像中。

与其他重载不同，该函数创建可以用于在图像上执行透视变换的转换矩阵。

另请参阅transformed()和图像变换。

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

返回图像的宽度。

另请参阅 图像信息。

QVariant QImage::operator QVariant() const

返回图像作为QVariant。

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

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

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

另请参阅operator=。

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

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

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

另请参阅 copy() 和 QImage。

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

将 other 移赋到当前的 QImage 实例。

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

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

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

另请参阅operator=。