QImage 类

QImage 类提供独立于硬件的图像表示 (允许直接访问像素数据，且可以用作描绘设备)。 更多...

头：	#include <QImage>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake:	QT += gui
继承：	QPaintDevice

• 所有成员列表，包括继承成员
• QImage 属于 描绘类 and 隐式共享类 .

注意： 此类的所有函数 可重入 .

公共类型

enum	Format { Format_Invalid, Format_Mono, Format_MonoLSB, Format_Indexed8, Format_RGB32, …, Format_RGBA32FPx4_Premultiplied }
enum	InvertMode { InvertRgb, InvertRgba }

公共函数

	QImage ()
	QImage (const QSize & size , QImage::Format format )
	QImage (int width , int height , QImage::Format format )
	QImage (uchar * data , int width , int height , QImage::Format format , QImageCleanupFunction cleanupFunction = nullptr, void * cleanupInfo = nullptr)
	QImage (const uchar * data , int width , int height , QImage::Format format , QImageCleanupFunction cleanupFunction = nullptr, void * cleanupInfo = nullptr)
	QImage (uchar * data , int width , int height , qsizetype bytesPerLine , QImage::Format format , QImageCleanupFunction cleanupFunction = nullptr, void * cleanupInfo = nullptr)
	QImage (const uchar * data , int width , int height , qsizetype bytesPerLine , QImage::Format format , QImageCleanupFunction cleanupFunction = nullptr, void * cleanupInfo = nullptr)
	QImage (const char *const[] xpm )
	QImage (const QString & fileName , const char * format = nullptr)
	QImage (const QImage & image )
	QImage (QImage && other )
virtual	~QImage ()
bool	allGray () const
void	applyColorTransform (const QColorTransform & transform )
int	bitPlaneCount () const
uchar *	bits ()
const uchar *	bits () const
qsizetype	bytesPerLine () const
qint64	cacheKey () const
QRgb	color (int i ) const
int	colorCount () const
QColorSpace	colorSpace () const
QList<QRgb>	colorTable () const
(从 6.4 起) QImage	colorTransformed (const QColorTransform & transform ) const &
(从 6.4 起) QImage	colorTransformed (const QColorTransform & transform ) &&
const uchar *	constBits () const
const uchar *	constScanLine (int i ) const
void	convertTo (QImage::Format format , Qt::ImageConversionFlags flags = Qt::AutoColor)
void	convertToColorSpace (const QColorSpace & colorSpace )
QImage	convertToFormat (QImage::Format format , Qt::ImageConversionFlags flags = Qt::AutoColor) const &
QImage	convertToFormat (QImage::Format format , Qt::ImageConversionFlags flags = Qt::AutoColor) &&
QImage	convertToFormat (QImage::Format format , const QList<QRgb> & colorTable , Qt::ImageConversionFlags flags = Qt::AutoColor) const
(从 6.0 起) QImage	convertedTo (QImage::Format format , Qt::ImageConversionFlags flags = Qt::AutoColor) const &
(从 6.0 起) QImage	convertedTo (QImage::Format format , Qt::ImageConversionFlags flags = Qt::AutoColor) &&
QImage	convertedToColorSpace (const QColorSpace & colorSpace ) const
QImage	copy (const QRect & rectangle = QRect()) const
QImage	copy (int x , int y , int width , int height ) const
QImage	createAlphaMask (Qt::ImageConversionFlags flags = Qt::AutoColor) const
QImage	createHeuristicMask (bool clipTight = true) const
QImage	createMaskFromColor (QRgb color , Qt::MaskMode mode = Qt::MaskInColor) const
int	depth () const
(从 6.2 起) QSizeF	deviceIndependentSize () const
qreal	devicePixelRatio () const
int	dotsPerMeterX () const
int	dotsPerMeterY () const
void	fill (uint pixelValue )
void	fill (const QColor & color )
void	fill (Qt::GlobalColor color )
QImage::Format	format () const
bool	hasAlphaChannel () const
int	height () const
void	invertPixels (QImage::InvertMode mode = InvertRgb)
bool	isGrayscale () const
bool	isNull () const
bool	load (const QString & fileName , const char * format = nullptr)
bool	load (QIODevice * device , const char * format )
(从 6.2 起) bool	loadFromData (QByteArrayView data , const char * format = nullptr)
bool	loadFromData (const uchar * data , int len , const char * format = nullptr)
bool	loadFromData (const QByteArray & data , const char * format = nullptr)
(从 6.0 起) void	mirror (bool horizontal = false, bool vertical = true)
QImage	mirrored (bool horizontal = false, bool vertical = true) const &
QImage	mirrored (bool horizontal = false, bool vertical = true) &&
QPoint	offset () const
QRgb	pixel (const QPoint & position ) const
QRgb	pixel (int x , int y ) const
QColor	pixelColor (const QPoint & position ) const
QColor	pixelColor (int x , int y ) const
QPixelFormat	pixelFormat () const
int	pixelIndex (const QPoint & position ) const
int	pixelIndex (int x , int y ) const
QRect	rect () const
bool	reinterpretAsFormat (QImage::Format format )
(从 6.0 起) void	rgbSwap ()
QImage	rgbSwapped () const &
QImage	rgbSwapped () &&
bool	save (const QString & fileName , const char * format = nullptr, int quality = -1) const
bool	save (QIODevice * device , const char * format = nullptr, int quality = -1) const
QImage	scaled (const QSize & size , Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation) const
QImage	scaled (int width , int height , Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation) const
QImage	scaledToHeight (int height , Qt::TransformationMode mode = Qt::FastTransformation) const
QImage	scaledToWidth (int width , Qt::TransformationMode mode = Qt::FastTransformation) const
uchar *	scanLine (int i )
const uchar *	scanLine (int i ) const
void	setAlphaChannel (const QImage & alphaChannel )
void	setColor (int index , QRgb colorValue )
void	setColorCount (int colorCount )
void	setColorSpace (const QColorSpace & colorSpace )
void	setColorTable (const QList<QRgb> & colors )
void	setDevicePixelRatio (qreal scaleFactor )
void	setDotsPerMeterX (int x )
void	setDotsPerMeterY (int y )
void	setOffset (const QPoint & offset )
void	setPixel (const QPoint & position , uint index_or_rgb )
void	setPixel (int x , int y , uint index_or_rgb )
void	setPixelColor (const QPoint & position , const QColor & color )
void	setPixelColor (int x , int y , const QColor & color )
void	setText (const QString & key , const QString & text )
QSize	size () const
qsizetype	sizeInBytes () const
void	swap (QImage & other )
QString	text (const QString & key = QString()) const
QStringList	textKeys () const
CGImageRef	toCGImage () const
(从 6.0 起) HBITMAP	toHBITMAP () const
(从 6.0 起) HICON	toHICON (const QImage & mask = {}) const
QImage	transformed (const QTransform & matrix , Qt::TransformationMode mode = Qt::FastTransformation) const
bool	valid (const QPoint & pos ) const
bool	valid (int x , int y ) const
int	width () const
QVariant	operator QVariant () const
bool	operator!= (const QImage & image ) const
QImage &	operator= (const QImage & image )
QImage &	operator= (QImage && other )
bool	operator== (const QImage & image ) const

静态公共成员

(从 6.2 起) QImage	fromData (QByteArrayView data , const char * format = nullptr)
QImage	fromData (const uchar * data , int size , const char * format = nullptr)
QImage	fromData (const QByteArray & data , const char * format = nullptr)
(从 6.0 起) QImage	fromHBITMAP (HBITMAP hbitmap )
(从 6.0 起) QImage	fromHICON (HICON icon )
QImage::Format	toImageFormat (QPixelFormat format )
QPixelFormat	toPixelFormat (QImage::Format format )
QTransform	trueMatrix (const QTransform & matrix , int width , int height )

相关非成员

	QImageCleanupFunction
QDataStream &	operator<< (QDataStream & stream , const QImage & image )
QDataStream &	operator>> (QDataStream & stream , QImage & image )

详细描述

Qt 为处理图像数据提供了 4 个类：QImage、 QPixmap , QBitmap and QPicture 。QImage 是为 I/O 和直接访问/操纵像素而设计并优化的，而 QPixmap 是为在屏幕上展示图像而设计并优化的。 QBitmap 只是方便类，继承 QPixmap ，确保 1 深度。最后， QPicture 类是描绘设备，它记录并重演 QPainter 命令。

由于 QImage 是 QPaintDevice 子类， QPainter 可以用于在图像上直接绘制。当使用 QPainter 在 QImage，描绘可以在当前 GUI 线程外的其它线程中履行。

QImage 类支持几种图像格式，描述通过 Format 枚举。这些包括单色、8 位、32 位且 Alpha 融合图像 (可用于所有 Qt 4.x 版本)。

QImage 提供了可以用于获取有关图像各种信息的一批函数。还有几个函数使图像能够变换。

QImage 对象可以按值传递，由于 QImage 类使用 隐式数据共享 。QImage 对象还可以被流化和比较。

注意： 若愿意加载 QImage 对象以静态 Qt 构建，参考 插件怎么样 .

警告： 在 QImage 上描绘采用格式 QImage::Format_Indexed8 不支持。

读写图像文件

QImage 提供了几种方式加载图像文件：可以加载文件当构造 QImage 对象时，或通过使用 load () 或 loadFromData () 函数稍后。QImage 还提供静态 fromData () 函数，从给定数据构造 QImage。当加载图像时，文件名可以引用实际磁盘文件，或引用应用程序的某一嵌入资源。见 Qt 资源系统 概述，了解如何在应用程序可执行文件中嵌入图像及其它资源文件的细节。

只需调用 save () 函数以保存 QImage 对象。

可获得支持的文件格式的完整列表，透过 QImageReader::supportedImageFormats () 和 QImageWriter::supportedImageFormats () 函数。可以将新文件格式添加作为插件。默认情况下，Qt 支持以下格式：

格式	描述	Qt 支持
BMP	Windows 位图	读/写
GIF	GIF (图形互换格式) 可选	读取
JPG	JPEG (联合摄影专家组)	读/写
JPEG	JPEG (联合摄影专家组)	读/写
PNG	PNG (便携式网络图形)	读/写
PBM	PBM (便携式位图)	读取
PGM	PGM (便携式灰度图)	读取
PPM	Portable Pixmap (便携式像素图)	读/写
XBM	X11 Bitmap (X11 位图)	读/写
XPM	X11 Pixmap (X11 像素图)	读/写

图像信息

QImage 提供了可以用于获取有关图像各种信息的一批函数：

	可用函数
几何体	The size (), width (), height (), dotsPerMeterX ()，和 dotsPerMeterY () 函数提供图像大小和宽高比的有关信息。 The rect () 函数返回图像的封闭矩形。 valid () 函数告诉给定坐标对是否在此矩形内。 offset () 函数返回图像意欲偏移的像素数，当相对于其它图像定位时，还可以操纵这使用 setOffset () 函数。
颜色	可以检索像素的颜色，通过将其坐标传递给 pixel () 函数。 pixel () 函数返回颜色如 QRgb 值独立于图像格式。 若是单色和 8 位图像， colorCount () 和 colorTable () 函数提供用于存储图像数据的颜色分量的有关信息： colorTable () 函数返回图像的整个颜色表。要获得单个条目，使用 pixelIndex () 函数检索给定坐标对的像素索引，然后使用 color () 函数检索颜色。注意，若手动创建 8 位图像，还必须设置图像的有效颜色表。 The hasAlphaChannel () 函数告诉是否有 Alpha 通道，若图像格式遵守的话。 allGray () 和 isGrayscale () 函数告诉图像的颜色是否都为灰度着色。 另请参阅 像素操纵 and 图像变换 章节。
文本	The text () 函数返回关联给定文本键的图像文本。图像的＝文本键的检索可以使用 textKeys () 函数。使用 setText () 函数能更改图像的文本。
低级信息	The depth () 函数返回图像的深度。支持的深度包括 1 位 (单色)、8 位、16 位、24 位及 32 位。 bitPlaneCount () 函数告诉使用的那些位是多少。更多信息见 图像格式 章节。 The format (), bytesPerLine ()，和 sizeInBytes () 函数提供存储在图像中的数据的有关低级信息。 The cacheKey () 函数返回唯一内容标识数为此 QImage 对象。

像素操纵

用于操纵图像像素的函数从属图像格式。原因是单色和 8 位图像基于索引并使用颜色查找表，而 32 位图像直接存储 ARGB 值。对于有关图像格式的更多信息，见 图像格式 章节。

若是 32 位图像， setPixel () 函数可以用于将给定坐标处的像素颜色，更改为按 ARGB 四元组指定的任何其它颜色。要制作合适 QRgb 值，使用 qRgb () (将默认 Alpha 分量添加到给定 RGB 值，即：创建不透明颜色) 或 qRgba () 函数。例如：

32 位
	QImage image(3, 3, QImage::Format_RGB32); QRgb value; value = qRgb(189, 149, 39); // 0xffbd9527 image.setPixel(1, 1, value); value = qRgb(122, 163, 39); // 0xff7aa327 image.setPixel(0, 1, value); image.setPixel(1, 0, value); value = qRgb(237, 187, 51); // 0xffedba31 image.setPixel(2, 1, value);

若是 8 位和单色图像，像素值只是来自图像颜色表的索引。因此 setPixel () 函数只可以用于将给定坐标处的像素颜色更改成来自图像颜色表的预定义颜色 (即：它只能改变像素的索引值)。要更改或添加颜色到图像的颜色表，使用 setColor () 函数。

颜色表中的条目是 ARGB 编码四元组按 QRgb 值。使用 qRgb () 和 qRgba () 函数制作合适 QRgb 值为用于 setColor () 函数。例如：

8 位
	QImage image(3, 3, QImage::Format_Indexed8); QRgb value; value = qRgb(122, 163, 39); // 0xff7aa327 image.setColor(0, value); value = qRgb(237, 187, 51); // 0xffedba31 image.setColor(1, value); value = qRgb(189, 149, 39); // 0xffbd9527 image.setColor(2, value); image.setPixel(0, 1, 0); image.setPixel(1, 0, 0); image.setPixel(1, 1, 2); image.setPixel(2, 1, 1);

对于每颜色通道超过 8 位的图像，方法 setPixelColor () 和 pixelColor () 可以用于设置和获取 QColor 值。

QImage 还提供 scanLine () 函数返回指向具有给定索引的扫描线处的像素数据的指针，和 bits () 函数返回指向第一像素数据的指针 (这相当于 scanLine(0) ).

图像格式

存储的每个像素在 QImage 由整数表示。整数的大小因格式而异。QImage 支持的几种图像格式的描述通过 Format 枚举。

单色图像的存储是使用 1 位索引到最多 2 颜色的颜色表。有 2 种不同类型的单色图像：大端在前 (MSB 优先) 或小端在前 (LSB 优先) 位次序。

8 位图像的存储是使用 8 位索引到颜色表，即，每像素拥有一字节。颜色表为 QList < QRgb >，和 QRgb typedef 相当于包含 0xAARRGGBB 格式 ARGB 四元组的无符号 int。

32 位图像没有颜色表；取而代之，每个像素包含 QRgb 值。有 3 种不同类型的 32 位图像分别存储 RGB (即 0xffRRGGBB)、ARGB 和预乘 ARGB 值。在预乘格式中，红色、绿色和蓝色通道乘以 Alpha 分量除以 255。

图像的格式可以被检索使用 format () 函数。使用 convertToFormat () 函数能将图像转换为另一种格式。 allGray () 和 isGrayscale () 函数分辨彩色图像是否可以安全地转换为灰度图像。

图像变换

QImage 支持许多用于创建新图像 (原始图像的变换版本) 的函数： createAlphaMask () 函数构建并返回 1 BPP (位每像素) 遮罩从此图像的 Alpha 缓冲，和 createHeuristicMask () 函数创建并返回 1 BPP (位每像素) 试探遮罩为此图像。后一函数的工作是通过从一角选择颜色，然后从所有边缘开始去除相应颜色的像素。

The mirrored () 函数返回期望方向的图像镜像， scaled () 返回比例缩放到期望尺度矩形的图像副本，和 rgbSwapped () 函数从 RGB 图像构造 BGR 图像。

The scaledToWidth () 和 scaledToHeight () 函数返回图像的比例缩放副本。

The transformed () 函数返回按给定变换矩阵和变换模式变换的图像副本：在内部，调节变换矩阵以补偿不想要的平移，即， transformed () 返回包含原始图像的所有变换点的最小图像。静态 trueMatrix () 函数返回用于变换图像的实际矩阵。

还有原位改变图像属性的函数：

函数	描述
setDotsPerMeterX ()	通过设置以物理米为单位的水平拟合像素数定义宽高比。
setDotsPerMeterY ()	通过设置以物理米为单位的垂直拟合像素数定义宽高比。
fill ()	采用给定像素值填充整个图像。
invertPixels ()	反转图像中的所有像素值使用给定 InvertMode 值。
setColorTable ()	设置用于变换颜色索引的颜色表。仅单色和 8 位格式。
setColorCount ()	重置颜色表大小。仅单色和 8 位格式。

另请参阅 QImageReader , QImageWriter , QPixmap , QSvgRenderer , 图像合成范例 ，和 涂鸦范例 .

成员类型文档编制

enum QImage:: Format

以下图像格式可用于 Qt。见表格后注意事项。

常量	值	描述
QImage::Format_Invalid	0	图像无效。
QImage::Format_Mono	1	图像的存储是使用 1 位每像素。字节首先与 MSB (最显著位) 一起打包。
QImage::Format_MonoLSB	2	图像的存储是使用 1 位每像素。字节首先与 LSB (低显著位) 一起打包。
QImage::Format_Indexed8	3	图像的存储是使用 8 位索引到颜色映射。
QImage::Format_RGB32	4	图像的存储是使用 32 位 RGB 格式 (0xffRRGGBB)。
QImage::Format_ARGB32	5	图像的存储是使用 32 位 ARGB 格式 (0xAARRGGBB)。
QImage::Format_ARGB32_Premultiplied	6	图像的存储是使用预乘 32 位 ARGB 格式 (0xAARRGGBB)，即红色、绿色和蓝色通道乘以 Alpha 分量除以 255 (若 RR、GG 或 BB 的值高于 Alpha 通道，结果未定义)。某些操作 (譬如：使用 Alpha 融合的图像合成) 使用预乘 ARGB32 比采用纯 ARGB32 更快。
QImage::Format_RGB16	7	图像的存储是使用 16 位 RGB 格式 (5-6-5)。
QImage::Format_ARGB8565_Premultiplied	8	图像的存储是使用预乘 24 位 ARGB 格式 (8-5-6-5)。
QImage::Format_RGB666	9	图像的存储是使用 24 位 RGB 格式 (6-6-6)。未使用的最显著位始终为 0。
QImage::Format_ARGB6666_Premultiplied	10	图像的存储是使用预乘 24 位 ARGB 格式 (6-6-6-6)。
QImage::Format_RGB555	11	图像的存储是使用 16 位 RGB 格式 (5-5-5)。未使用的最显著位始终为 0。
QImage::Format_ARGB8555_Premultiplied	12	图像的存储是使用预乘 24 位 ARGB 格式 (8-5-5-5)。
QImage::Format_RGB888	13	图像的存储是使用 24 位 RGB 格式 (8-8-8)。
QImage::Format_RGB444	14	图像的存储是使用 16 位 RGB 格式 (4-4-4)。未使用位始终为 0。
QImage::Format_ARGB4444_Premultiplied	15	图像的存储是使用预乘 16 位 ARGB 格式 (4-4-4-4)。
QImage::Format_RGBX8888 (since Qt 5.2)	16	图像的存储是使用 32 位字节序 RGB(x) 格式 (8-8-8-8)。这如同 Format_RGBA8888，除 Alpha 必须始终为 255 外。
QImage::Format_RGBA8888 (since Qt 5.2)	17	图像的存储是使用 32 位字节序 RGBA 格式 (8-8-8-8)。不像 ARGB32，这是字节序格式，意味着 32 位编码在大端和小端体系结构之间会有所不同，分别是 (0xRRGGBBAA) 和 (0xAABBGGRR)。颜色的次序在任何体系结构都相同，若按字节 0xRR、0xGG、0xBB、0xAA 读取。
QImage::Format_RGBA8888_Premultiplied (since Qt 5.2)	18	图像的存储是使用预乘 32 位字节序 RGBA 格式 (8-8-8-8)。
QImage::Format_BGR30 (since Qt 5.4)	19	图像的存储是使用 32 位 BGR 格式 (x-10-10-10)。
QImage::Format_A2BGR30_Premultiplied (since Qt 5.4)	20	图像的存储是使用 32 位预乘 ABGR 格式 (2-10-10-10)。
QImage::Format_RGB30 (since Qt 5.4)	21	图像的存储是使用 32 位 RGB 格式 (x-10-10-10)。
QImage::Format_A2RGB30_Premultiplied (since Qt 5.4)	22	图像的存储是使用 32 位预乘 ARGB 格式 (2-10-10-10)。
QImage::Format_Alpha8 (since Qt 5.5)	23	图像的存储是使用 8 位仅 Alpha 格式。
QImage::Format_Grayscale8 (since Qt 5.5)	24	图像的存储是使用 8 位灰度格式。
QImage::Format_Grayscale16 (since Qt 5.13)	28	The image is stored using an 16-bit grayscale format.
QImage::Format_RGBX64 (since Qt 5.12)	25	The image is stored using a 64-bit halfword-ordered RGB(x) format (16-16-16-16). This is the same as the Format_RGBA64 except alpha must always be 65535.
QImage::Format_RGBA64 (since Qt 5.12)	26	The image is stored using a 64-bit halfword-ordered RGBA format (16-16-16-16).
QImage::Format_RGBA64_Premultiplied (since Qt 5.12)	27	The image is stored using a premultiplied 64-bit halfword-ordered RGBA format (16-16-16-16).
QImage::Format_BGR888 (since Qt 5.14)	29	The image is stored using a 24-bit BGR format.
QImage::Format_RGBX16FPx4 (since Qt 6.2)	30	The image is stored using a four 16-bit halfword floating point RGBx format (16FP-16FP-16FP-16FP). This is the same as the Format_RGBA16FPx4 except alpha must always be 1.0.
QImage::Format_RGBA16FPx4 (since Qt 6.2)	31	The image is stored using a four 16-bit halfword floating point RGBA format (16FP-16FP-16FP-16FP).
QImage::Format_RGBA16FPx4_Premultiplied (since Qt 6.2)	32	The image is stored using a premultiplied four 16-bit halfword floating point RGBA format (16FP-16FP-16FP-16FP).
QImage::Format_RGBX32FPx4 (since Qt 6.2)	33	The image is stored using a four 32-bit floating point RGBx format (32FP-32FP-32FP-32FP). This is the same as the Format_RGBA32FPx4 except alpha must always be 1.0.
QImage::Format_RGBA32FPx4 (since Qt 6.2)	34	The image is stored using a four 32-bit floating point RGBA format (32FP-32FP-32FP-32FP).
QImage::Format_RGBA32FPx4_Premultiplied (since Qt 6.2)	35	The image is stored using a premultiplied four 32-bit floating point RGBA format (32FP-32FP-32FP-32FP).

注意： 绘制进 QImage 采用 QImage::Format_Indexed8 不支持。

注意： 避免大多数直接渲染到大多数这些格式使用 QPainter 。最好优化渲染针对 Format_RGB32 and Format_ARGB32_Premultiplied 格式，和其次是渲染到 Format_RGB16 , Format_RGBX8888 , Format_RGBA8888_Premultiplied , Format_RGBX64 and Format_RGBA64_Premultiplied 格式

另请参阅 format () 和 convertToFormat ().

enum QImage:: InvertMode

此枚举类型用于描述应如何反转像素值在 invertPixels () 函数。

常量	值	描述
QImage::InvertRgb	0	仅反转 RGB 值并使 Alpha 通道保持不变。
QImage::InvertRgba	1	反转所有通道，包括 Alpha 通道。

另请参阅 invertPixels ().

成员函数文档编制

QImage QImage:: convertToFormat ( QImage::Format format , Qt::ImageConversionFlags flags = Qt::AutoColor) &&

QImage QImage:: convertToFormat ( QImage::Format format , Qt::ImageConversionFlags flags = Qt::AutoColor) const &

返回图像副本按给定 format .

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

另请参阅 convertTo () 和 图像格式 .

[since 6.0] QImage QImage:: convertedTo ( QImage::Format format , Qt::ImageConversionFlags flags = Qt::AutoColor) &&

[since 6.0] QImage QImage:: convertedTo ( QImage::Format format , Qt::ImageConversionFlags flags = Qt::AutoColor) const &

返回图像副本按给定 format .

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

该函数在 Qt 6.0 引入。

另请参阅 convertTo () 和 图像格式 .

QImage QImage:: mirrored ( bool horizontal = false, bool vertical = true) &&

QImage QImage:: mirrored ( bool horizontal = false, bool vertical = true) const &

返回图像的镜像，在水平和/或垂直方向上镜像取决于是否 horizontal and vertical 被设为 true 或 false。

注意：原始图像不改变。

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

QImage QImage:: rgbSwapped () &&

QImage QImage:: rgbSwapped () const &

返回 QImage ，所有像素的红色和蓝色分量值被交换，将 RGB 图像高效转换成 BGR 图像。

原始 QImage 不改变。

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

[noexcept] QImage:: QImage ()

构造空图像。

另请参阅 isNull ().

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

构造图像采用给定 size and format .

A null 图像被返回，若无法分配内存。

警告： 这将创建带有未初始化数据的 QImage。调用 fill () 采用适当像素值填充图像，先于绘制它采用 QPainter .

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

构造图像采用给定 width , height and format .

A null 图像将被返回，若无法分配内存。

警告： 这将创建带有未初始化数据的 QImage。调用 fill () 采用适当像素值填充图像，先于绘制它采用 QPainter .

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

构造图像采用给定 width , height and format ，使用现有内存缓冲 data 。 width and height 必须指定以像素为单位， data 必须 32 位对齐，且图像中的每一数据扫描线也必须 32 位对齐。

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

若 format 是索引颜色格式，图像颜色表最初将为空，且必须充分扩展采用 setColorCount () 或 setColorTable () 在图像被使用之前。

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

构造图像采用给定 width , height and format ，使用现有只读内存缓冲， data 。 width and height 必须指定以像素为单位， data 必须 32 位对齐，且图像中的每一数据扫描线也必须 32 位对齐。

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

若 format 是索引颜色格式，图像颜色表最初将为空，且必须充分扩展采用 setColorCount () 或 setColorTable () 在图像被使用之前。

不像类似 QImage 构造函数接受非 const 数据缓冲，此版本从不更改缓冲内容。例如，调用 QImage::bits () 将返回图像的深拷贝，而不是传递给构造函数的缓冲。这允许高效构造 QImage 从原生数据，不可能改变原生数据。

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

构造图像采用给定 width , height and format ，使用现有内存缓冲 data 。 width and height 必须指定以像素为单位。 bytesPerLine 指定每行的字节数 (步幅)。

缓冲必须在 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 and format ，使用现有内存缓冲 data 。 width and height 必须指定以像素为单位。 bytesPerLine 指定每行的字节数 (步幅)。

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

若 format 是索引颜色格式，图像颜色表最初将为空，且必须充分扩展采用 setColorCount () 或 setColorTable () 在图像被使用之前。

不像类似 QImage 构造函数接受非 const 数据缓冲，此版本从不更改缓冲内容。例如，调用 QImage::bits () 将返回图像的深拷贝，而不是传递给构造函数的缓冲。这允许高效构造 QImage 从原生数据，不可能改变原生数据。

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

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

构造图像并试着从文件加载图像，采用给定 fileName .

加载器试图读取图像使用指定 format 。若 format 未指定 (默认)，它将基于文件后缀和 Header (头) 自动检测。有关细节，见 { QImageReader::setAutoDetectImageFormat ()}{ QImageReader }.

若图像加载失败，此对象为 null 图像。

文件名可以引用实际磁盘文件，或引用应用程序的某一嵌入资源。见 资源系统 概述，了解如何在应用程序可执行文件中嵌入图像及其它资源文件的细节。

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

QImage:: QImage (const QImage & image )

构造浅拷贝为给定 image .

有关浅拷贝的更多信息，见 隐式数据共享 文档编制。

另请参阅 copy ().

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

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

[virtual 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 使用 隐式数据共享 ，但此函数执行 not 对共享像素数据履行深拷贝，因为返回数据是 const。

qsizetype QImage:: bytesPerLine () const

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

这相当于 sizeInBytes () / height () 若 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

返回图像的颜色表大小。

注意，colorCount() 返回 0 对于 32 BPP (位每像素) 图像，因为这些图像不使用颜色表，取而代之是将像素值编码成 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 &

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

该函数在 Qt 6.4 引入。

另请参阅 applyColorTransform ().

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

这是重载函数。

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

该函数在 Qt 6.4 引入。

另请参阅 applyColorTransform ().

const uchar *QImage:: constBits () const

返回第一像素数据指针。

注意， QImage 使用 隐式数据共享 ，但此函数执行 not 对共享像素数据履行深拷贝，因为返回数据是 const。

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

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

返回像素数据的指针在扫描线索引 i 。第一扫描线在索引 0。

扫描线数据按最小 32 位对齐。对于 64 位格式，它遵循 64 位整数的本机对齐 (大多数平台为 64 位，但 i386 为 32 位)。

注意， QImage 使用 隐式数据共享 ，但此函数执行 not 对共享像素数据履行深拷贝，因为返回数据是 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 ().

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

这是重载函数。

返回图像的副本将转换到给定 format ，使用指定 colorTable .

从 RGB 格式到索引格式的转换是很缓慢的操作，且会使用没有抖动的直接最近颜色方式。

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

返回图像转换到 colorSpace .

若图像没有有效色彩空间，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 是 null 矩形，整个图像被拷贝。

另请参阅 QImage ().

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

这是重载函数。

返回的图像拷贝自位置 ( x , y ) 在此图像中，且将始终拥有给定 width and height 。在此图像外的区域，像素被设为 0。

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

从此图像的 Alpha 缓冲构建并返回 1 BPP (位每像素) 遮罩。返回 null 图像，若图像格式为 QImage::Format_RGB32 .

The flags 自变量是按位 OR 的 Qt::ImageConversionFlags ，和控制转换过程。为标志传递 0 将设置所有默认选项。

返回图像拥有小端在前位次序 (即：图像的格式为 QImage::Format_MonoLSB )，可以转换到大端在前 ( QImage::Format_Mono ) 使用 convertToFormat () 函数。

另请参阅 createHeuristicMask () 和 图像变换 .

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

为此图像创建并返回 1 BPP (位每像素) 试探遮罩。

函数的工作是通过从一角选择颜色，然后从所有边缘开始去除相应颜色的像素。4 角投票要遮住哪种颜色。若绘制 (这通常意味着此函数不适用于图像)，结果是任意的。

返回图像拥有小端在前位次序 (即：图像的格式为 QImage::Format_MonoLSB )，可以转换到大端在前 ( QImage::Format_Mono ) 使用 convertToFormat () 函数。

若 clipTight 为 true (默认)，遮罩刚好足够大以覆盖像素；否则，遮罩 > 数据像素。

注意：此函数忽视 Alpha 缓冲。

另请参阅 createAlphaMask () 和 图像变换 .

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 (), 图像格式 ，和 图像信息 .

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

返回设备无关的图像大小，以像素为单位。

应使用此值，当使用图像大小计算用户界面尺寸时。

返回值相当于 image. size () / image. devicePixelRatio ().

该函数在 Qt 6.2 引入。

qreal QImage:: devicePixelRatio () const

返回图像的设备像素比率。此比率介于 设备像素 and 设备无关像素 .

使用此函数当基于图像大小计算布局几何体时： QSize layoutSize = 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，仅使用最低位。若为 fill(0)、fill(2) 等，采用 0 填充图像。若为 fill(1)、fill(3) 等，采用 1 图像填充。若深度为 8，使用最低 8 位，和若深度为 16，使用最低 16 位。

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

注意： 不存在相应值 Getter，虽然 QImage::pixelIndex () 会返回相同值对于索引格式，和 QImage::pixel () 对于 RGB32、ARGB32 及 ARGB32PM 格式。

另请参阅 depth () 和 图像变换 .

void QImage:: fill (const QColor & color )

这是重载函数。

填充整个图像采用给定 color .

若图像深度为 1，图像将被填充采用 1 若 color 等于 Qt::color1 ；否则，将采用 0 填充它。

若图像深度为 8，填充图像采用的索引对应 color 在颜色表中 (若存在)；否则，将采用 0 填充它。

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

这是重载函数。

填充图像采用给定 color ，描述为标准全局颜色。

QImage::Format QImage:: format () const

返回图像格式。

另请参阅 图像格式 .

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

构造图像从给定 QByteArrayView data 。加载器试图读取图像使用指定 format 。若 format 未 指定 (默认)，加载器会探针头数据以猜测文件格式。

若 format 有指定，它必须是某一值返回通过 QImageReader::supportedImageFormats ().

若图像加载失败，返回图像将为 null 图像。

该函数在 Qt 6.2 引入。

另请参阅 load (), save ()，和 读写图像文件 .

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

这是重载函数。

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

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

这是重载函数。

构造 QImage 从给定 QByteArray data .

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

返回 QImage 相当于给定 hbitmap .

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 )

返回 QImage 相当于给定 icon .

该函数在 Qt 6.0 引入。

另请参阅 toHICON ().

bool QImage:: hasAlphaChannel () const

返回 true 若图像拥有的格式遵守 Alpha 通道，否则返回 false .

另请参阅 图像信息 .

int QImage:: height () const

返回图像的高度。

另请参阅 图像信息 .

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

反转图像所有像素值。

给定反转 mode 才有意义当图像深度为 32 时。默认 mode is InvertRgb ，使 Alpha 通道保持不变。若 mode is InvertRgba ，Alpha 位也反转。

反转 8 位图像意味着替换所有像素，使用颜色索引 i 采用像素使用颜色索引 255 减 i 。1 位图像的情况也如此。注意，颜色表 not 改变。

若图像拥有预乘 Alpha 通道，则首先将图像转换成待反转的未预乘图像格式，然后再转换回来。

另请参阅 图像变换 .

bool QImage:: isGrayscale () const

对于 32 位图像，此函数相当于 allGray ().

对于颜色索引图像，此函数返回 true 若 color(i) 为 QRgb (i, i, i) 对于颜色表所有索引而言；否则返回 false .

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

bool QImage:: isNull () const

返回 true 若它是 null 图像，否则返回 false .

null 图像的所有参数都设置为零，并且没有分配的数据。

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

从文件加载图像采用给定 fileName 。返回 true 若成功加载图像；否则使图像无效并返回 false .

加载器试图读取图像使用指定 format ，如 PNG 或 JPG。若 format 未指定 (默认)，它将基于文件后缀和 Header (头) 自动检测。有关细节，见 QImageReader::setAutoDetectImageFormat ().

文件名可以引用实际磁盘文件，或引用应用程序的某一嵌入资源。见 资源系统 概述，了解如何在应用程序可执行文件中嵌入图像及其它资源文件的细节。

另请参阅 读写图像文件 .

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

这是重载函数。

此函数读取 QImage 从给定 device 。例如，这可以用于将图像直接加载到 QByteArray .

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

加载图像从给定 QByteArrayView data 。返回 true 若成功加载图像；否则使图像无效并返回 false .

加载器试图读取图像使用指定 format ，如 PNG 或 JPG。若 format 未指定 (默认)，加载器会探针文件 Header (头) 以猜测文件格式。

该函数在 Qt 6.2 引入。

另请参阅 读写图像文件 .

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

这是重载函数。

加载图像从第一 len 字节的给定二进制 data .

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

这是重载函数。

加载图像从给定 QByteArray data .

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

图像在水平和/或垂直方向的镜像，从属是否 horizontal and vertical 被设为 true 或 false。

该函数在 Qt 6.0 引入。

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

QPoint QImage:: offset () const

返回图像相对于其它图像定位时，打算偏移的像素数。

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

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

返回像素的颜色在给定 position .

若 position 无效，结果未定义。

警告： 此函数很昂贵，当用于操纵大规模像素时。使用 constBits () 或 constScanLine () 当需要读取很多像素时。

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

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

这是重载函数。

返回像素的颜色按坐标 ( x , y ).

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

返回像素的颜色在给定 position 作为 QColor .

若 position 无效，无效 QColor 被返回。

警告： 此函数很昂贵，当用于操纵大规模像素时。使用 constBits () 或 constScanLine () 当需要读取很多像素时。

另请参阅 setPixelColor (), setPixel (), valid (), constBits (), constScanLine ()，和 像素操纵 .

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 ()，和 像素操纵 .

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 通道的图像更改为相应不透明格式 (若已知数据为仅不透明)，或改变给定图像缓冲的格式 (在采用新数据覆盖它前)。

警告： 函数不校验图像数据在新格式中是否有效，且仍返回 true 若深度是兼容的。对具有无效数据的图像的操作未定义。

警告： 若图像未分离，这将导致数据被拷贝。

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

保存图像到文件采用给定 fileName ，使用给定图像文件 format and quality 因子。若 format is nullptr , QImage 将试图猜测格式通过查看 fileName 的后缀。

The quality 因子必须在 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 and transformMode .

• 若 aspectRatioMode is Qt::IgnoreAspectRatio ，图像被比例缩放到 size .
• 若 aspectRatioMode is Qt::KeepAspectRatio ，图像被比例缩放到尽可能大的矩形，不超出 size , 保留宽高比。
• 若 aspectRatioMode is Qt::KeepAspectRatioByExpanding ，图像被比例缩放到矩形尽可能小地大于 size , 保留宽高比。

若给定 size 为空，此函数返回 null 图像。

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

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

这是重载函数。

返回的图像副本被比例缩放到矩形采用给定 width and height 根据给定 aspectRatioMode and transformMode .

若 width 或 height 为 0 或负数，此函数返回 null 图像。

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

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

此函数自动计算图像宽度，以便保留图像比率。

若给定 height 为 0 或负数，返回 null 图像。

另请参阅 图像变换 .

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

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

此函数自动计算图像高度，以便保留其宽高比。

若给定 width 为 0 或负数，返回 null 图像。

另请参阅 图像变换 .

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));
    }
}
		

警告： 若正访问 32 BPP (位每像素) 图像数据，则返回指针会被铸造成 QRgb* ( QRgb 拥有 32 位大小) 并使用它来读/写像素值。无法使用 uchar* 指针直接，因为像素格式从属底层平台字节序。使用 qRed (), qGreen (), qBlue ()，和 qAlpha () 来访问像素。

另请参阅 bytesPerLine (), bits (), 像素操纵 ，和 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 通道，则将它转换成相应格式。

操作类似于描绘 alphaChannel 作为覆盖此图像的 Alpha 图像使用 QPainter::CompositionMode_DestinationIn .

另请参阅 hasAlphaChannel (), 图像变换 ，和 图像格式 .

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

设置颜色在给定 index 在颜色表中，到给定 colorValue 。颜色值是 ARGB 四元组。

若 index 超出颜色表当前大小，展开它采用 setColorCount ().

另请参阅 color (), colorCount (), setColorTable ()，和 像素操纵 .

void QImage:: setColorCount ( int colorCount )

重置颜色表大小以包含 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。将它设为其它值有 2 种效果：

打开图像时将比例缩放 QPainter。例如，若比率为 2.0，200x200 图像的描绘将导致 (设备无关) 100x100 的有效描绘边界。

Qt 中基于图像大小计算布局几何体的代码路径，会考虑比率： QSize layoutSize = image. size () / image. devicePixelRatio () 这的净效果是图像显示成高 DPI (每英寸点数) 图像，而不是大图像 (见 绘制高分辨率版本的像素图和图像 ).

另请参阅 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 to index_or_rgb .

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

若 position 不是有效图像坐标对，或者若 index_or_rgb >= colorCount () 在单色和调色板图像情况下，结果未定义。

警告： 此函数很昂贵由于调用了内部 detach() 函数在调用内；若涉及性能，推荐使用 scanLine () 或 bits () 以直接访问像素数据。

另请参阅 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 to color .

若 position 不是有效图像坐标对，或图像格式为单色 (或调色板)，结果未定义。

警告： 此函数很昂贵由于调用了内部 detach() 函数在调用内；若涉及性能，推荐使用 scanLine () 或 bits () 以直接访问像素数据。

另请参阅 pixelColor (), pixel (), bits (), scanLine ()，和 像素操纵 .

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

这是重载函数。

设置像素颜色在 ( x , y ) 到 color .

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

将图像文本设为给定 text 并将其关联到给定 key .

若仅仅想要存储单文本块 (即：comment 或仅仅描述)，可以传递空键，或使用像 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 ().

另请参阅 图像信息 and deviceIndependentSize ().

qsizetype QImage:: sizeInBytes () const

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

另请参阅 bytesPerLine (), bits ()，和 图像信息 .

[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

创建 CGImage 等效于此 QImage .

返回 CGImageRef 句柄。

返回的 CGImageRef 参与 QImage 隐式共享，和保持引用 QImage 数据。CGImage 不可变且从不分离 QImage 。写入 QImage 通常会分离。

此函数很快，且不会拷贝 (或转换) 图像数据。

支持以下图像格式，且会映射到本机相应图像类型：

Qt	CoreGraphics
Format_ARGB32	kCGImageAlphaFirst | kCGBitmapByteOrder32Host
Format_RGB32	kCGImageAlphaNoneSkipFirst | kCGBitmapByteOrder32Host
Format_RGBA8888_Premultiplied	kCGImageAlphaPremultipliedLast | kCGBitmapByteOrder32Big
Format_RGBA8888	kCGImageAlphaLast | kCGBitmapByteOrder32Big
Format_RGBX8888	kCGImageAlphaNoneSkipLast | kCGBitmapByteOrder32Big
Format_ARGB32_Premultiplied	kCGImageAlphaPremultipliedFirst | kCGBitmapByteOrder32Host

不支持其它格式；此函数为这些情况返回 null 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

创建 HICON 相当于 QPixmap ，应用遮罩 mask .

若 mask 不是 null，它需要为格式 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 () 和 图像变换 .

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

返回用于变换图像的实际矩阵采用给定 width , height and matrix .

当变换图像使用 transformed () 函数，变换矩阵在内部调节以补偿不想要的平移，即 transformed () 返回包含原始图像中所有变换点的最小图像。此函数返回修改矩阵，将来自原始图像中的点正确地映射到新图像。

不像其它重载，此函数创建可以用于对图像履行透视变换的变换矩阵。

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

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

返回 true if pos 是图像中的有效坐标对；否则返回 false .

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

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

这是重载函数。

返回 true if QPoint ( x , y ) 是图像中的有效坐标对；否则返回 false .

int QImage:: width () const

返回图像宽度。

另请参阅 图像信息 .

QVariant QImage:: operator QVariant () const

将图像返回作为 QVariant .

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

返回 true 若此图像和给定 image 拥有不同内容；否则返回 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

返回 true 若此图像和给定 image 拥有相同内容；否则返回 false .

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

另请参阅 operator= ().

相关非成员

QImageCleanupFunction

具有以下签名的函数，可用于实现基本图像内存管理：

void myImageCleanupHandler(void *info);
		

QDataStream & operator<< ( QDataStream & stream , const QImage & image )

写入给定 image 到给定 stream 作为 PNG 图像，或作为 BMP 图像若流的版本为 1。注意：将流写入文件不会产生有效图像文件。

另请参阅 QImage::save () 和 序列化 Qt 数据类型 .

QDataStream & operator>> ( QDataStream & stream , QImage & image )

读取图像从给定 stream 并把它存储在给定 image .

另请参阅 QImage::load () 和 序列化 Qt 数据类型 .

内容

• 公共类型

• 公共函数

• 静态公共成员

• 相关非成员

• 详细描述

• 读写图像文件

• 图像信息

• 像素操纵

• 图像格式

• 图像变换